vue-composable
    TypeScript icon, indicating that this package has built-in type declarations

    1.0.0-beta.24 • Public • Published

    vue-composable

    vue-composable logo

    CircleCI Coverage Status npm version bundle size

    Out-of-the-box ready to use composables

    • 🌴 TreeShakable
    • 🧙‍♂️ Fully Typescript
    • 💚 Vue 3 and 2 support
    • 🔨 Vue Devtools support

    Introduction

    This library aim is to be one stop shop for many real-world composable functions, with aggressive tree-shaking to keep it light on your end code.

    Installing

    # @vue/composition-api
    
    # install with yarn
    yarn add @vue/composition-api vue-composable
    
    # install with npm
    npm install @vue/composition-api vue-composable
    
    # vue 3
    
    # install with yarn
    yarn add vue-composable
    
    # install with npm
    npm install vue-composable

    Documentation

    Check our documentation

    Composable

    Event

    • Event - Attach event listener to a DOM element
    • Mouse Move - Attach mousemove listener to a DOM element
    • Resize - Attach resize listener to a DOM element
    • Scroll - Attach scroll listener to a DOM element
    • onOutsidePress - Execute callback when click is outside of element

    Dom

    Date

    • useNow : Return reactive custom timer with specified refresh rate
    • useDateNow : Returns reactive Date.now() with custom refresh rate
    • usePerformanceNow : Returns reactive performance.now() with custom refresh rate

    Format

    • format - Reactive string format
    • path - Retrieve object value based on string path

    Breakpoint

    MISC

    Storage

    • WebStorage - Reactive access to Storage API, useLocalStorage and useSessionStorage use this
    • storage - uses localStorage or on safari private it uses sessionStorage
    • localStorage - Reactive access to a localStorage
    • sessionStorage - Reactive access to a sessionStorage

    Pagination

    Validation

    i18n

    • i18n - Simple i18n implementation with API inspired by vue-i18n

    Intl

    Promise

    Meta

    • Title - reactive document.title

    State

    • Timeline - Tracks variable history
    • Undo - Tracks variable history, to allow undo and redo
    • valueSync - syncs variables value, across multiple refs

    Web

    External

    New packages needed

    Information

    This is a monorepo project, please check packages

    Devtools

    There's some experimental devtools support starting from 1.0.0-beta.6, only available for vue-next and devtools beta 6.

    Install plugin

    To use devtools you need to install the plugin first:

    import { createApp } from "vue";
    import { VueComposableDevtools } from "vue-composable";
    import App from "./App.vue";
    
    const app = createApp(App);
    app.use(VueComposableDevtools);
    // or
    app.use(VueComposableDevtools, {
      id: "vue-composable",
      label: "devtool composables"
    });
    
    app.mount("#app");

    Component State

    To add properties to the component inspector tab ComponentState

    const bar = "bar";
    useDevtoolsComponentState(
      {
        bar
      },
      {
        type: "custom composable" // change group
      }
    );
    
    const baz = () => "baz";
    useDevtoolsComponentState({ baz });
    // no duplicates added by default
    useDevtoolsComponentState({ baz });
    
    const the = 42;
    useDevtoolsComponentState({ the });
    // to allow multiple same key
    useDevtoolsComponentState({ the }, { duplicate: true });
    
    // use a devtools api list directly
    interface StateBase {
      key: string;
      value: any;
      editable: boolean;
      objectType?: "ref" | "reactive" | "computed" | "other";
      raw?: string;
      type?: string;
    }
    useDevtoolsComponentState([
      {
        key: "_bar",
        type: "direct",
        value: "bar",
        editable: true
      },
      {
        key: "_baz",
        type: "direct",
        value: "baz",
        editable: false
      }
    ]);
    
    // raw change
    useDevtoolsComponentState((payload, ctx) => {
      payload.state.push(
        ...[
          {
            key: "_bar",
            type: "raw",
            value: "bar",
            editable: true
          },
          {
            key: "_baz",
            type: "raw",
            value: "baz",
            editable: false
          }
        ]
      );
    });

    Timeline events

    To add timeline events:

    const id = "vue-composable";
    const label = "Test events";
    const color = 0x92a2bf;
    
    const { addEvent, pushEvent } = useDevtoolsTimelineLayer(
      id,
      description,
      color
    );
    
    // adds event to a specific point in the timeline
    addEvent({
      time: Date.now(),
      data: {
        // data object
      },
      meta: {
        // meta object
      }
    });
    
    // adds event with `time: Date.now()`
    pushEvent({
      data: {
        // data object
      },
      meta: {
        // meta object
      }
    });

    Inspector

    Allows to create a new inspector for your data.

    I'm still experimenting on how to expose this API on a composable, this will likely to change in the future, suggestions are welcome.

    useDevtoolsInspector(
      {
        id: "vue-composable",
        label: "test vue-composable"
      },
      // list of nodes, this can be reactive
      [
        {
          id: "test",
          label: "test - vue-composable",
          depth: 0,
          state: {
            composable: [
              {
                editable: false,
                key: "count",
                objectType: "Ref",
                type: "setup",
                value: myRefValue
              }
            ]
          }
        }
      ]
    );

    Typescript

    Typescript@3.x is not supported, the supported version can be checked on package.json, usually is the latest version or the same major as vue-3

    Contributing

    You can contribute raising issues and by helping out with code.

    Tests and Documentation are the most important things for me, because good documentation is really useful!

    I really appreciate some tweaks or changes on how the documentation is displayed and how to make it easier to read.

    Twitter: @pikax_dev

    Build

    # install packages
    yarn
    
    # build and test for v2
    yarn build --version=2
    yarn test:vue2
    
    # build and test for v3
    yarn build
    yarn test

    New composable

    1. Fork it!
    2. Create your feature branch: git checkout -b feat/new-composable
    3. Commit your changes: git commit -am 'feat(composable): add a new composable'
    4. Push to the branch: git push origin feat/new-composable
    5. Submit a pull request

    License

    MIT

    Install

    npm i vue-composable

    DownloadsWeekly Downloads

    3,198

    Version

    1.0.0-beta.24

    License

    MIT

    Unpacked Size

    1.81 MB

    Total Files

    27

    Last publish

    Collaborators

    • pikax