@toife/vue 3.0.0 → 3.0.1

package/README.md

@@ -2,6 +2,59 @@
 
 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 |
@@ -160,7 +213,7 @@ import { utils } from "@toife/vue";
 // utils.* — see exports under src/utils
 ```
 
-See `src/utils` in the repo for concrete APIs.
+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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toife/vue",
-  "version": "3.0.0",
+  "version": "3.0.1",
   "description": "A Frontend framework for Vue",
   "type": "module",
   "sideEffects": false,
@@ -20,7 +20,7 @@
     "frontend",
     "web"
   ],
-  "author": "Toikit",
+  "author": "Toivibe",
   "license": "MIT",
   "publishConfig": {
     "access": "public",
@@ -34,12 +34,10 @@
   },
   "scripts": {
     "dev": "vite",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsc",
     "build": "vite build",
     "format": "prettier . --write",
-    "prepare": "husky",
-    "test:dev": "vite --config test/vite.config.ts",
-    "test:build": "vite build --config test/vite.config.ts"
+    "prepare": "husky"
   },
   "lint-staged": {
     "*.{js,ts,vue,json,css,scss,sass,md,html}": "prettier --write"
@@ -56,7 +54,6 @@
     "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"
   },

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

@@ -11,14 +11,13 @@ $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");
-$background-color: sass.fn-naming-var("surface", "background-color");
 $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("item", "border-color");
+$border-color: sass.fn-naming-var("action", "border-color");
 
 .#{$action} {
   // Styles

package/src/components/action/action.vue

@@ -28,34 +28,22 @@ const pop = ref(false);
 
 /// Computed
 /// ------------------------------------------------------------
-const divider = computed(() => {
-  return (props?.divider !== undefined ? props.divider : appState?.divider.value) ?? false;
-});
-
-const shadow = computed(() => {
-  return (props?.shadow !== undefined ? props.shadow : appState?.shadow.value) ?? false;
-});
-
-const shape = computed(() => {
-  return props.shape ?? appState?.shape.value ?? "";
-});
-
-const role = computed(() => {
-  return props.role ?? appState?.role.value ?? "";
-});
-
 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", "surface"]),
-      withPrefix(["role", role.value]),
-      withPrefix(["shape", shape.value]),
+      withPrefix(["layer", "action"]),
+      withPrefix(["role", role]),
+      withPrefix(["shape", shape]),
       props.placement,
       {
         pop: pop.value,
-        divider: divider.value,
-        shadow: shadow.value,
+        divider,
+        shadow,
       },
     ],
   };

package/src/components/app/app.md

@@ -0,0 +1,77 @@
+# `<t-app>`
+
+> Default prefix is `t-` — change via `createToife({ prefix: "..." })`.
+
+## Description
+
+Library root layout: provides theme/context (`provide`) for descendants, mounts multiple `Toast` regions by placement, and hosts `Action` / `DecisionModal` when using `useAction` / `useDecisionModal`.
+
+## Requirements / dependencies
+
+| Item  | Notes                |
+| ----- | -------------------- |
+| Vue   | ^3.5                 |
+| Other | Router not required. |
+
+## Basic usage
+
+```vue
+<template>
+  <t-app>
+    <t-page>App content</t-page>
+  </t-app>
+</template>
+```
+
+## Props
+
+| Prop        | Type                | Default  | Description                                      |
+| ----------- | ------------------- | -------- | ------------------------------------------------ |
+| `shape`     | `string`            | `"pill"` | Default shape for children (buttons, fields, …). |
+| `divider`   | `boolean`           | `false`  | Default divider flag.                            |
+| `role`      | `string`            | `"mode"` | Default theme role.                              |
+| `shadow`    | `boolean`           | `false`  | Default shadow.                                  |
+| `triple`    | `boolean`           | `false`  | Layout flag (provided to children).              |
+| `direction` | `"left" \| "right"` | `"left"` | Direction (fields, …).                           |
+
+**Type source:** `src/components/app/app.type.ts`
+
+## Events (emits)
+
+_No public emits._
+
+## Slots
+
+| Slot      | Description                                           |
+| --------- | ----------------------------------------------------- |
+| `default` | Main app content.                                     |
+| `global`  | Extra slot (after default, before internal overlays). |
+
+## `v-model`
+
+No.
+
+## Provide / inject / context
+
+`provide(APP_PROVIDER_STATE_KEY)`: `{ shape, divider, role, shadow, triple, direction }` — children inject for consistent theming.
+
+## Expose
+
+Nothing.
+
+## Special behavior
+
+- Renders several `Toast` instances with fixed placements (top/bottom × start/center/end).
+- When `useAction()` / `useDecisionModal()` has `data`, renders the matching `Action` / `DecisionModal`.
+
+## Accessibility (a11y)
+
+Wrapper only; no special root role.
+
+## Style / class notes
+
+Classes: `layer`, `base`, `shape`, `app`.
+
+## See also
+
+- Source: `src/components/app`

package/src/components/app/app.scss

@@ -3,9 +3,9 @@
 // Class name
 $app: sass.fn-naming-prefix("app");
 
-// Property name - layer: base
-$background-color: sass.fn-naming-var("base", "background-color");
-$color: sass.fn-naming-var("base", "color");
+// Property name - layer: app
+$background-color: sass.fn-naming-var("app", "background-color");
+$color: sass.fn-naming-var("app", "color");
 $transition-duration: sass.fn-naming-var("motion", "duration");
 
 .#{$app} {

package/src/components/app/app.vue

@@ -28,7 +28,7 @@ const action = useAction();
 // Present attributes
 const appAttrs = computed(() => {
   return {
-    class: [withPrefix(["layer", "base"]), withPrefix(["shape", shape.value]), withPrefix("app")],
+    class: [withPrefix(["layer", "app"]), withPrefix(["shape", shape.value]), withPrefix("app")],
   };
 });
 

package/src/components/avatar/avatar.md

@@ -0,0 +1,64 @@
+# `<t-avatar>`
+
+> Default prefix is `t-` — change via `createToife({ prefix: "..." })`.
+
+## Description
+
+Displays an avatar image as a CSS `background-image` inside a themed frame (shape/role from app when omitted).
+
+## Requirements / dependencies
+
+| Item  | Notes                                             |
+| ----- | ------------------------------------------------- |
+| Vue   | ^3.5                                              |
+| Other | `t-app` recommended for default `role` / `shape`. |
+
+## Basic usage
+
+```vue
+<t-avatar src="/user.png" size="40px" />
+```
+
+## Props
+
+| Prop    | Type               | Default  | Description                           |
+| ------- | ------------------ | -------- | ------------------------------------- |
+| `shape` | `string`           | —        | Shape override; default from `t-app`. |
+| `size`  | `string \| number` | `"22px"` | Size (number is treated as px).       |
+| `src`   | `string`           | `""`     | Image URL for background.             |
+
+**Type source:** `src/components/avatar/avatar.type.ts`
+
+## Events (emits)
+
+_None._
+
+## Slots
+
+| Slot      | Description                    |
+| --------- | ------------------------------ |
+| `default` | Optional inner content (rare). |
+
+## `v-model`
+
+No.
+
+## Provide / inject
+
+Injects `AppProviderState` for `role` / `shape`.
+
+## Expose
+
+Nothing.
+
+## Accessibility (a11y)
+
+Decorative background image — add `aria-label` on a parent if a name must be announced.
+
+## Style / class notes
+
+CSS variable `--<prefix>-width` via `property("width")`.
+
+## See also
+
+- Source: `src/components/avatar`

package/src/components/avatar/avatar.scss

@@ -4,9 +4,9 @@
 $avatar: sass.fn-naming-prefix("avatar");
 $shape-pill: sass.fn-naming-prefix("shape-pill");
 
-// Property - layer: surface
+// Property - layer: avatar
 $border-radius: sass.fn-naming-var("border-radius");
-$background-color: sass.fn-naming-var("surface", "background-color");
+$background-color: sass.fn-naming-var("avatar", "background-color");
 $width: sass.fn-naming-var("width");
 $transition-duration: sass.fn-naming-var("motion", "duration");
 

package/src/components/avatar/avatar.vue

@@ -22,7 +22,7 @@ const avatarAttrs = computed(() => {
 
   return {
     class: [
-      withPrefix(["layer", "surface"]),
+      withPrefix(["layer", "avatar"]),
       withPrefix(["role", role]),
       withPrefix(["shape", shape]),
       withPrefix("avatar"),

package/src/components/button/button.md

@@ -0,0 +1,66 @@
+# `<t-button>`
+
+> Default prefix is `t-` — change via `createToife({ prefix: "..." })`.
+
+## Description
+
+Button with variants, sizes, loading state, and theming from `t-app`.
+
+## Requirements / dependencies
+
+| Item  | Notes                                                |
+| ----- | ---------------------------------------------------- |
+| Vue   | ^3.5                                                 |
+| Other | `t-app` recommended for `shape` / `role` / `shadow`. |
+
+## Basic usage
+
+```vue
+<t-button variant="fill" @click="save">Save</t-button>
+<t-button loading>Loading</t-button>
+```
+
+## Props
+
+| Prop      | Type                               | Default      | Description                              |
+| --------- | ---------------------------------- | ------------ | ---------------------------------------- |
+| `role`    | `string`                           | —            | Theme role; default from app.            |
+| `size`    | `"small" \| "standard" \| "large"` | `"standard"` | Size.                                    |
+| `shape`   | `string`                           | —            | Shape; default from app.                 |
+| `block`   | `boolean`                          | `false`      | Full-width button.                       |
+| `loading` | `boolean`                          | `false`      | Hides label, shows `loading` slot.       |
+| `variant` | `ButtonVariant`                    | `"fill"`     | `fill` \| `outline` \| `text` \| `link`. |
+| `shadow`  | `boolean`                          | —            | Default from app if unset.               |
+
+**Type source:** `src/components/button/button.type.ts`
+
+## Events (emits)
+
+_No declared emits_ — use native DOM listeners (`@click`).
+
+## Slots
+
+| Slot      | Description                           |
+| --------- | ------------------------------------- |
+| `default` | Button label (hidden when `loading`). |
+| `loading` | Content when `loading`.               |
+
+## `v-model`
+
+No.
+
+## Provide / inject
+
+Injects theme from `t-app`.
+
+## Expose
+
+Nothing.
+
+## Accessibility (a11y)
+
+Native `<button>`; focus/blur styling handled internally.
+
+## See also
+
+- Source: `src/components/button`

package/src/components/button/button.scss

@@ -11,14 +11,14 @@ $transition-duration: sass.fn-naming-var("motion", "duration");
 $spacing-x: sass.fn-naming-var("spacing", "x");
 $spacing-y: sass.fn-naming-var("spacing", "y");
 
-$color: sass.fn-naming-var("item", "color");
+$color: sass.fn-naming-var("button", "color");
 
-$border-color: sass.fn-naming-var("item", "border-color");
-$border-color-hover: sass.fn-naming-var("item", "border-color", "strong");
-$border-color-focus: sass.fn-naming-var("item", "border-color", "heavy");
-$border-color-active: sass.fn-naming-var("item", "border-color", "heavy");
-$border-color-disabled: sass.fn-naming-var("item", "border-color");
-$border-color-inactive: sass.fn-naming-var("item", "border-color", "soft");
+$border-color: sass.fn-naming-var("button", "border-color");
+$border-color-hover: sass.fn-naming-var("button", "border-color", "strong");
+$border-color-focus: sass.fn-naming-var("button", "border-color", "heavy");
+$border-color-active: sass.fn-naming-var("button", "border-color", "heavy");
+$border-color-disabled: sass.fn-naming-var("button", "border-color");
+$border-color-inactive: sass.fn-naming-var("button", "border-color", "soft");
 
 $size-font-size: sass.fn-naming-var("font-size");
 $size-height: sass.fn-naming-var("height");
@@ -26,12 +26,12 @@ $size-coefficient-x: sass.fn-naming-var("coefficient-x");
 $size-coefficient-y: sass.fn-naming-var("coefficient-y");
 $size-line-height: sass.fn-naming-var("line-height");
 
-$background-color: sass.fn-naming-var("item", "background-color");
-$background-color-hover: sass.fn-naming-var("item", "background-color", "strong");
-$background-color-focus: sass.fn-naming-var("item", "background-color", "heavy");
-$background-color-active: sass.fn-naming-var("item", "background-color", "heavy");
-$background-color-disabled: sass.fn-naming-var("item", "background-color");
-$background-color-inactive: sass.fn-naming-var("item", "background-color", "soft");
+$background-color: sass.fn-naming-var("button", "background-color");
+$background-color-hover: sass.fn-naming-var("button", "background-color", "strong");
+$background-color-focus: sass.fn-naming-var("button", "background-color", "heavy");
+$background-color-active: sass.fn-naming-var("button", "background-color", "heavy");
+$background-color-disabled: sass.fn-naming-var("button", "background-color");
+$background-color-inactive: sass.fn-naming-var("button", "background-color", "soft");
 
 .#{$button} {
   display: inline-flex;

package/src/components/button/button.vue

@@ -23,17 +23,14 @@ const isFocused = ref(false);
 
 /// Computed
 /// ------------------------------------------------------------
-const shadow = computed(() => {
-  return (props?.shadow !== undefined ? props.shadow : appState?.shadow.value) ?? false;
-});
-
 const buttonAttrs = computed(() => {
   const shape = props.shape || appState?.shape.value || "";
   const role = props.role || appState?.role.value || "";
+  const shadow = (props?.shadow !== undefined ? props.shadow : appState?.shadow.value) ?? false;
 
   return {
     class: [
-      withPrefix(["layer", "item"]),
+      withPrefix(["layer", "button"]),
       withPrefix(["role", role]),
       withPrefix(["shape", shape]),
       withPrefix("button"),
@@ -41,18 +38,16 @@ const buttonAttrs = computed(() => {
       props.variant,
       {
         block: props.block,
-        shadow: shadow.value,
+        shadow,
         focus: isFocused.value,
       },
     ],
   };
 });
 
-const loaderAttrs = computed(() => {
-  return {
-    class: [withPrefix("loader")],
-  };
-});
+const loaderAttrs = {
+  class: [withPrefix("loader")],
+} as const;
 
 /// Methods
 /// ------------------------------------------------------------