@toife/vue 2.2.0 → 3.0.1

package/README.md

@@ -0,0 +1,224 @@
+# @toife/vue
+
+Vue 3 component library for Toife. The package ships **source** (`src/`): your app bundles it and compiles Sass with your own configuration.
+
+## Documentation
+
+Usage docs live **next to source** under `src/`. Authoring scaffold: [docs/template.md](docs/template.md).
+
+### Components
+
+| Doc | Tag / export |
+|-----|----------------|
+| [action.md](src/components/action/action.md) | `t-action` |
+| [app.md](src/components/app/app.md) | `t-app` |
+| [avatar.md](src/components/avatar/avatar.md) | `t-avatar` |
+| [button.md](src/components/button/button.md) | `t-button` |
+| [cable.md](src/components/cable/cable.md) | `t-cable` |
+| [card.md](src/components/card/card/card.md) | `t-card` |
+| [card-header.md](src/components/card/card-header/card-header.md) | `t-card-header` |
+| [card-body.md](src/components/card/card-body/card-body.md) | `t-card-body` |
+| [card-footer.md](src/components/card/card-footer/card-footer.md) | `t-card-footer` |
+| [checkbox.md](src/components/checkbox/checkbox.md) | `t-checkbox` |
+| [collapse.md](src/components/collapse/collapse.md) | `t-collapse` |
+| [container.md](src/components/container/container.md) | `t-container` |
+| [decision-modal.md](src/components/decision-modal/decision-modal.md) | `t-decision-modal` |
+| [divider.md](src/components/divider/divider.md) | `t-divider` |
+| [field.md](src/components/field/field.md) | `t-field` |
+| [form-group.md](src/components/form-group/form-group.md) | `t-form-group` |
+| [gesture-indicator.md](src/components/gesture-indicator/gesture-indicator.md) | `t-gesture-indicator` |
+| [image.md](src/components/image/image.md) | `t-image` |
+| [modal.md](src/components/modal/modal.md) | `t-modal` |
+| [page.md](src/components/page/page.md) | `t-page` |
+| [present.md](src/components/present/present.md) | `Present` (named import; not in `createToife`) |
+| [radio.md](src/components/radio/radio/radio.md) | `t-radio` |
+| [radio-group.md](src/components/radio/radio-group/radio-group.md) | `t-radio-group` |
+| [refresher.md](src/components/refresher/refresher.md) | `t-refresher` |
+| [route-navigator.md](src/components/route/route-navigator/route-navigator.md) | `t-route-navigator` |
+| [route-wrapper.md](src/components/route/route-wrapper/route-wrapper.md) | `t-route-wrapper` |
+| [route-provider.md](src/components/route/route-provider/route-provider.md) | `t-route-provider` |
+| [route-outlet.md](src/components/route/route-outlet/route-outlet.md) | `t-route-outlet` |
+| [segmented-field.md](src/components/segmented-field/segmented-field.md) | `t-segmented-field` |
+| [skeleton.md](src/components/skeleton/skeleton.md) | `t-skeleton` |
+| [switch.md](src/components/switch/switch.md) | `t-switch` |
+| [tab.md](src/components/tabs/tab/tab.md) | `Tab` (named import; not in `createToife`) |
+| [tabs.md](src/components/tabs/tabs/tabs.md) | `t-tabs` |
+| [toast.md](src/components/toast/toast/toast.md) | `t-toast` |
+| [toast-content.md](src/components/toast/toast-content/toast-content.md) | `t-toast-content` |
+| [toolbar.md](src/components/toolbar/toolbar.md) | `t-toolbar` |
+
+### Utils
+
+| Doc | Contents |
+|-----|----------|
+| [element.md](src/utils/element.md) | `isFormElement`, `blurCurrentActive` |
+| [events.md](src/utils/events.md) | `preventDefault` |
+| [style.md](src/utils/style.md) | `withPrefix`, `property`, `variable`, … |
+
+## Requirements
+
+| Package | Notes |
+|---------|--------|
+| `vue` ^3.5 | Required |
+| `vue-router` ^4 | Required when using route-related components |
+| `@toife/gesture` | Gestures |
+| `@toife/sass-layer-generator` | Component SCSS uses `@use`; install in the app and configure Sass (e.g. Vite `css.preprocessorOptions`) |
+
+## Installation
+
+```bash
+npm install @toife/vue
+# or
+yarn add @toife/vue
+```
+
+Install any missing peer dependencies if npm/yarn reports them.
+
+## Global registration (plugin)
+
+`createToife()` registers most components as **kebab-case** tags with the default prefix `t-`.
+
+```ts
+// main.ts
+import { createApp } from "vue";
+import { createToife } from "@toife/vue";
+import App from "./App.vue";
+
+const app = createApp(App);
+app.use(createToife());
+// or change the prefix:
+// app.use(createToife({ prefix: "toife-" })); // → <toife-app>, <toife-button>, ...
+app.mount("#app");
+```
+
+```vue
+<!-- Example: default prefix "t-" -->
+<template>
+  <t-app>
+    <t-page>
+      <t-toolbar />
+      <t-container>
+        <t-button>OK</t-button>
+      </t-container>
+    </t-page>
+  </t-app>
+</template>
+```
+
+### `createToife` options
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `prefix` | `string` | `"t-"` | Tag name prefix (e.g. `my-` → `<my-button>`) |
+
+## Tags after `app.use(createToife())`
+
+The default prefix is `t-`. The **Tag** column is `prefix` + name (e.g. `t-button`).
+
+| Tag (prefix `t-`) | Component |
+|-------------------|-----------|
+| `t-app` | App |
+| `t-action` | Action |
+| `t-avatar` | Avatar |
+| `t-button` | Button |
+| `t-cable` | Cable |
+| `t-card` | Card |
+| `t-card-body` | CardBody |
+| `t-card-header` | CardHeader |
+| `t-card-footer` | CardFooter |
+| `t-checkbox` | Checkbox |
+| `t-radio` | Radio |
+| `t-radio-group` | RadioGroup |
+| `t-collapse` | Collapse |
+| `t-container` | Container |
+| `t-decision-modal` | DecisionModal |
+| `t-divider` | Divider |
+| `t-field` | Field |
+| `t-form-group` | FormGroup |
+| `t-gesture-indicator` | GestureIndicator |
+| `t-image` | Image |
+| `t-modal` | Modal |
+| `t-page` | Page |
+| `t-present` | Present |
+| `t-refresher` | Refresher |
+| `t-route-navigator` | RouteNavigator |
+| `t-route-wrapper` | RouteWrapper |
+| `t-route-provider` | RouteProvider |
+| `t-route-outlet` | RouteOutlet |
+| `t-segmented-field` | SegmentedField |
+| `t-skeleton` | Skeleton |
+| `t-switch` | Switch |
+| `t-tabs` | Tabs |
+| `t-toast` | Toast |
+| `t-toast-content` | ToastContent |
+| `t-toolbar` | Toolbar |
+
+### Components not registered by the plugin
+
+These are **still exported** from `@toife/vue` but are **not** included in `createToife().install` — import them directly and call `app.component(...)` yourself if you need globals:
+
+- `Tab` — used inside `Tabs`; `import { Tab, Tabs } from "@toife/vue"`.
+- `OutlineField` — `import { OutlineField } from "@toife/vue"`.
+
+```ts
+import { Tab, OutlineField } from "@toife/vue";
+
+app.component("t-tab", Tab);
+app.component("t-outline-field", OutlineField);
+```
+
+Or use them only in SFCs: `import { Tab } from "@toife/vue"` and register locally / use in a parent template.
+
+## Named imports (without the plugin)
+
+You can always import components and register them manually or use them locally:
+
+```vue
+<script setup lang="ts">
+import { Button, App, RouteNavigator, RouteWrapper } from "@toife/vue";
+</script>
+
+<template>
+  <App>
+    <RouteWrapper>
+      <RouteNavigator variant="swipe" />
+    </RouteWrapper>
+  </App>
+</template>
+```
+
+Public exports are defined in `src/index.ts` (factory, re-exported `./components`, and `utils`).
+
+## Vue Router
+
+`RouteNavigator`, `RouteWrapper`, `RouteProvider`, and `RouteOutlet` expect `vue-router` to be installed and configured in your app.
+
+## TypeScript
+
+The package includes `*.vue` declarations via the entry; if your IDE still complains about `.vue` modules, add this to your project (Vite):
+
+```ts
+// env.d.ts
+declare module "*.vue" {
+  import type { DefineComponent } from "vue";
+  const component: DefineComponent<{}, {}, any>;
+  export default component;
+}
+```
+
+## Utilities
+
+```ts
+import { utils } from "@toife/vue";
+// utils.* — see exports under src/utils
+```
+
+See [src/utils/element.md](src/utils/element.md), [src/utils/events.md](src/utils/events.md), [src/utils/style.md](src/utils/style.md) and `src/utils/*.ts` for concrete APIs.
+
+## Sass / theming
+
+Component styles use `@use "@toife/sass-layer-generator"` and SCSS under `src`. Configure **sass-embedded** / **sass** and any aliases in **your** app so tokens, layers, and variables resolve when you build.
+
+## License
+
+MIT

package/package.json

@@ -1,13 +1,18 @@
 {
   "name": "@toife/vue",
-  "version": "2.2.0",
+  "version": "3.0.1",
   "description": "A Frontend framework for Vue",
   "type": "module",
-  "main": "dist/index.umd.js",
-  "module": "dist/index.es.js",
-  "types": "dist/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
   "files": [
-    "dist"
+    "src"
   ],
   "keywords": [
     "vue",
@@ -15,21 +20,45 @@
     "frontend",
     "web"
   ],
-  "author": "Toikit",
+  "author": "Toivibe",
   "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
   "peerDependencies": {
     "@toife/gesture": "^1.1.4",
-    "vue": "^3.5.19",
-    "vue-router": "^4.5.1"
+    "@toife/sass-layer-generator": "^1.0.9",
+    "vue": "^3.5.0",
+    "vue-router": "^4.0.0"
   },
   "scripts": {
-    "build": "vite build"
+    "dev": "vite",
+    "typecheck": "tsc",
+    "build": "vite build",
+    "format": "prettier . --write",
+    "prepare": "husky"
+  },
+  "lint-staged": {
+    "*.{js,ts,vue,json,css,scss,sass,md,html}": "prettier --write"
   },
   "devDependencies": {
+    "@commitlint/cli": "^20.4.4",
+    "@commitlint/config-conventional": "^20.4.4",
+    "@toife/sass-layer-generator": "^1.0.9",
+    "@types/node": "^25.0.3",
     "@vitejs/plugin-vue": "^6.0.1",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.4.0",
+    "prettier": "3.7.4",
     "sass": "^1.90.0",
     "typescript": "^5.9.2",
     "vite": "^7.0.6",
-    "vite-plugin-dts": "^4.5.4"
+    "vue": "^3.5.0",
+    "vue-router": "^4.0.0"
+  },
+  "packageManager": "yarn@4.12.0",
+  "dependencies": {
+    "@toife/gesture": "^1.1.4"
   }
 }

package/src/components/action/action.composable.ts

@@ -0,0 +1,32 @@
+import { ref } from "vue";
+import type { ActionButton, ActionComposableProps } from "./action.type";
+
+const data = ref<ActionComposableProps | null>(null);
+const visible = ref(false);
+
+export const useAction = () => {
+  const open = (props: ActionComposableProps) => {
+    data.value = props;
+    setTimeout(() => {
+      visible.value = true;
+    }, 50);
+  };
+
+  const close = (type?: string) => {
+    data.value?.onClose?.(type);
+    visible.value = false;
+  };
+
+  const choose = (btn: ActionButton) => {
+    data.value?.onChoose?.(btn);
+    visible.value = false;
+  };
+
+  return {
+    open,
+    close,
+    choose,
+    visible,
+    data,
+  };
+};

package/src/components/action/action.html

@@ -0,0 +1,25 @@
+<Present
+  :placement="placement"
+  backdrop="display"
+  :keepalive="false"
+  :visible="visible"
+  @close="onClose"
+>
+  <div v-bind="actionAttrs">
+    <slot name="body">
+      <FormGroup orientation="vertical" v-for="(buttons, groupIndex) in actions" :key="groupIndex">
+        <CustomButton
+          v-for="(btn, btnIndex) in buttons"
+          :key="`${groupIndex}-${btnIndex}`"
+          :role="btn.role"
+          :variant="btn.variant"
+          @click="onChoose(btn)"
+          :shape="shape"
+          :shadow="btn.shadow !== undefined ? btn.shadow : shadow"
+          block
+          >{{ btn.text }}</CustomButton
+        >
+      </FormGroup>
+    </slot>
+  </div>
+</Present>

package/src/components/action/action.md

@@ -0,0 +1,115 @@
+# `<t-action>`
+
+> Default prefix is `t-` — change via `createToife({ prefix: "..." })`.
+
+## Description
+
+Action sheet: groups of buttons rendered inside `Present`, typically for quick choices or secondary menus. Control via props or the `useAction()` composable wired by `t-app`.
+
+## Requirements / dependencies
+
+| Item  | Notes                                                                                     |
+| ----- | ----------------------------------------------------------------------------------------- |
+| Vue   | ^3.5                                                                                      |
+| Other | Prefer `t-app` for theme/context (`inject`). Depends on `Present`, `FormGroup`, `Button`. |
+
+## Basic usage
+
+```vue
+<template>
+  <t-action
+    :visible="show"
+    :actions="[[{ text: 'Confirm', variant: 'fill', handler: onOk }]]"
+    placement="bottom"
+    @close="show = false"
+    @choose="onChoose"
+  />
+</template>
+```
+
+Or open via `useAction()` (wired by `t-app`):
+
+```ts
+import { useAction } from "@toife/vue";
+
+const action = useAction();
+action.open({
+  actions: [[{ text: "OK", handler: () => {} }]],
+  onClose: () => {},
+  onChoose: (btn) => {},
+});
+```
+
+## Props
+
+| Prop        | Type                    | Default      | Description                                                    |
+| ----------- | ----------------------- | ------------ | -------------------------------------------------------------- |
+| `visible`   | `boolean`               | `false`      | Show the action layer.                                         |
+| `dismiss`   | `string[]`              | —            | `Present` close reasons that emit `close` (e.g. `'backdrop'`). |
+| `actions`   | `Array<ActionButton[]>` | _(required)_ | Rows of button groups; each row is an array of buttons.        |
+| `role`      | `string`                | —            | Theme role override; default from `t-app`.                     |
+| `shape`     | `string`                | —            | Shape override; default from `t-app`.                          |
+| `divider`   | `boolean`               | —            | Divider; default from `t-app`.                                 |
+| `shadow`    | `boolean`               | —            | Shadow; default from `t-app`.                                  |
+| `placement` | `PresentPlacement`      | `"bottom"`   | `Present` placement (`top`, `bottom`, …).                      |
+
+**Type source:** `src/components/action/action.type.ts`
+
+`ActionButton`: `text`, `role`, `variant`, `shadow`, `handler`, `data`.
+
+## Events (emits)
+
+| Event    | Payload             | Description                                               |
+| -------- | ------------------- | --------------------------------------------------------- |
+| `close`  | `type?: string`     | When `dismiss` matches the close reason.                  |
+| `choose` | `btn: ActionButton` | After a button is chosen (after that button’s `handler`). |
+
+## Slots
+
+| Slot   | Slot props | Description                                  |
+| ------ | ---------- | -------------------------------------------- |
+| `body` | —          | Replaces the default button layout entirely. |
+
+## `v-model`
+
+No `v-model` support.
+
+## Provide / inject / context
+
+Injects `APP_PROVIDER_STATE_KEY` from `t-app` for `divider`, `shadow`, `shape`, `role` when props are omitted.
+
+## Expose (template ref)
+
+Nothing exposed.
+
+## Special behavior
+
+- Backdrop close: if the payload is not in `dismiss`, a short `pop` animation runs instead of emitting `close`.
+
+## Accessibility (a11y)
+
+Inherits from `Present` (backdrop, focus). Buttons use inner `Button`.
+
+## Style / class notes
+
+BEM-style classes via `withPrefix`: `action`, `layer`, `surface`, `role`, `shape`, placement, `pop`, `divider`, `shadow`.
+
+## Advanced example
+
+```vue
+<t-action
+  :visible="open"
+  :dismiss="['backdrop']"
+  :actions="[
+    [{ text: 'Cancel', variant: 'text', handler: cancel }],
+    [{ text: 'Delete', variant: 'fill', role: 'danger', handler: remove }],
+  ]"
+  placement="bottom"
+  @close="(t) => console.log(t)"
+/>
+```
+
+## See also
+
+- Source: `src/components/action`
+- Composable: `action.composable.ts` (`useAction`)

package/src/components/action/action.scss

@@ -0,0 +1,105 @@
+@use "@toife/sass-layer-generator" as sass;
+
+// Class name
+$action: sass.fn-naming-prefix("action");
+$button: sass.fn-naming-prefix("button");
+
+// Property name
+$margin-y: sass.fn-naming-var("spacing", "y");
+$margin-x: sass.fn-naming-var("spacing", "x");
+$width: sass.fn-naming-var("viewport", "width");
+$max-width: sass.fn-naming-var("overlay", "max-width");
+$height: sass.fn-naming-var("viewport", "height");
+$max-height: sass.fn-naming-var("overlay", "max-height");
+$transition-duration: sass.fn-naming-var("motion", "duration");
+$safe-area-bottom: sass.fn-naming-var("safe-area", "bottom");
+$safe-area-top: sass.fn-naming-var("safe-area", "top");
+$safe-area-left: sass.fn-naming-var("safe-area", "left");
+$safe-area-right: sass.fn-naming-var("safe-area", "right");
+$border-width: sass.fn-naming-var("stroke", "width");
+$border-color: sass.fn-naming-var("action", "border-color");
+
+.#{$action} {
+  // Styles
+  display: flex;
+  flex-direction: column;
+  justify-content: center;
+  align-items: center;
+  column-gap: calc(#{$margin-y} * 2);
+  row-gap: calc(#{$margin-x} * 2);
+  border-width: #{$border-width};
+
+  &.top,
+  &.bottom {
+    width: #{$width};
+
+    > div {
+      width: 100%;
+      max-width: #{$max-width};
+    }
+  }
+
+  &.bottom {
+    margin-bottom: calc(#{$margin-y} * 4 + #{$safe-area-bottom});
+  }
+
+  &.top {
+    margin-top: calc(#{$margin-y} * 4 + #{$safe-area-top});
+  }
+
+  &.left,
+  &.right {
+    > div {
+      width: 100%;
+      max-width: #{$max-width};
+    }
+  }
+
+  &.left {
+    margin-left: calc(#{$margin-x} * 4 + #{$safe-area-left});
+  }
+
+  &.right {
+    margin-right: calc(#{$margin-x} * 4 + #{$safe-area-right});
+  }
+
+  &.pop {
+    animation: pop #{$transition-duration} ease-in-out;
+  }
+
+  &.divider {
+    :deep(.#{$button}) {
+      border-color: transparent;
+      border-bottom-color: rgb(#{$border-color});
+    }
+  }
+
+  &:not(.divider) {
+    :deep(.#{$button}) {
+      border-color: transparent;
+    }
+  }
+}
+
+// Effect when click outside action modal
+@keyframes pop {
+  0% {
+    transform: scale(1);
+  }
+
+  50% {
+    transform: scale(1.1);
+  }
+
+  70% {
+    transform: scale(1);
+  }
+
+  80% {
+    transform: scale(1.1);
+  }
+
+  100% {
+    transform: scale(1);
+  }
+}

package/src/components/action/action.type.ts

@@ -0,0 +1,35 @@
+import { ButtonVariant } from "../button/button.type";
+import { PresentPlacement } from "../present";
+
+export type ActionPlacement = PresentPlacement;
+
+// Define
+export type ActionButton = {
+  text?: string;
+  role?: string;
+  variant?: ButtonVariant;
+  shadow?: boolean;
+  handler?: () => void;
+  data?: unknown;
+};
+
+export type ActionProps = {
+  visible?: boolean;
+  dismiss?: string[];
+  actions: Array<ActionButton[]>;
+  role?: string;
+  shape?: string;
+  divider?: boolean;
+  shadow?: boolean;
+  placement?: ActionPlacement;
+};
+
+export type ActionComposableProps = ActionProps & {
+  onClose?: (type?: string) => void;
+  onChoose?: (btn?: ActionButton) => void;
+};
+
+export type ActionEmit = {
+  (e: "close", type?: string): void;
+  (e: "choose", btn: ActionButton): void;
+};

package/src/components/action/action.vue

@@ -0,0 +1,70 @@
+<style lang="scss" src="./action.scss" scoped></style>
+<template src="./action.html"></template>
+<script lang="ts" setup>
+import { computed, inject, ref } from "vue";
+import { Present } from "../present";
+import { Button as CustomButton } from "../button";
+import { FormGroup } from "../form-group";
+import { type ActionEmit, type ActionButton, type ActionProps } from "./action.type";
+import { withPrefix } from "../../utils";
+import { type AppProviderState, APP_PROVIDER_STATE_KEY } from "../app";
+
+/// Define
+/// ------------------------------------------------------------
+const appState = inject<AppProviderState>(APP_PROVIDER_STATE_KEY);
+const emit = defineEmits<ActionEmit>();
+const props = withDefaults(defineProps<ActionProps>(), {
+  visible: false,
+  shape: undefined,
+  role: undefined,
+  placement: "bottom",
+  divider: undefined,
+  shadow: undefined,
+});
+
+/// State
+/// ------------------------------------------------------------
+const pop = ref(false);
+
+/// Computed
+/// ------------------------------------------------------------
+const actionAttrs = computed(() => {
+  const divider = (props?.divider !== undefined ? props.divider : appState?.divider.value) ?? false;
+  const shadow = (props?.shadow !== undefined ? props.shadow : appState?.shadow.value) ?? false;
+  const shape = props.shape ?? appState?.shape.value ?? "";
+  const role = props.role ?? appState?.role.value ?? "";
+  return {
+    class: [
+      withPrefix("action"),
+      withPrefix(["layer", "action"]),
+      withPrefix(["role", role]),
+      withPrefix(["shape", shape]),
+      props.placement,
+      {
+        pop: pop.value,
+        divider,
+        shadow,
+      },
+    ],
+  };
+});
+
+/// Methods
+/// ------------------------------------------------------------
+const onClose = (val: string) => {
+  if (props.dismiss && props.dismiss.includes(val)) {
+    emit("close", val);
+  } else if (val === "backdrop") {
+    pop.value = true;
+    setTimeout(() => {
+      pop.value = false;
+    }, 300);
+  }
+};
+
+const onChoose = (btn: ActionButton) => {
+  emit("close");
+  btn.handler?.();
+  emit("choose", btn);
+};
+</script>

package/src/components/action/index.ts

@@ -0,0 +1,9 @@
+export { default as Action } from "./action.vue";
+export type {
+  ActionProps,
+  ActionEmit,
+  ActionButton,
+  ActionPlacement,
+  ActionComposableProps,
+} from "./action.type";
+export { useAction } from "./action.composable";