@lovince/ui-vue 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lovince Tech
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,135 @@
-# Temporary Holding Version
+# @lovince/ui-vue
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Accessible, unstyled Vue 3 components for Lovince UI. Every component is a
+state machine from [`@lovince/ui-headless`](../ui-headless); its browser
+effects run through [`@lovince/ui-dom`](../ui-dom). This package subscribes to
+the machine, feeds props in, and renders what `connect()` returns. It holds no
+behaviour of its own.
+
+> **Status: `0.1.0`, experimental.** The API may change before `1.0`.
+
+```bash
+bun add @lovince/ui-vue
+```
+
+Requires Vue 3.5+ (for SSR-stable `useId`). No CSS ships with the package. Style
+it with classes and the `data-*` state attributes, or use
+[`@lovince/themes`](../themes) for tokens.
+
+## Components
+
+| Group | Component | Parts |
+|---|---|---|
+| Disclosure | Disclosure | `DisclosureRoot`, `DisclosureTrigger`, `DisclosureContent` |
+| | Accordion | `AccordionRoot`, `AccordionItem`, `AccordionHeader`, `AccordionTrigger`, `AccordionContent` |
+| | Tabs | `TabsRoot`, `TabsList`, `TabsTrigger`, `TabsContent` |
+| Overlays | Dialog | `DialogRoot`, `DialogTrigger`, `DialogPortal`, `DialogOverlay`, `DialogContent`, `DialogTitle`, `DialogDescription`, `DialogClose` |
+| | Popover | `PopoverRoot`, `PopoverTrigger`, `PopoverAnchor`, `PopoverPortal`, `PopoverContent`, `PopoverClose` |
+| | Tooltip | `TooltipRoot`, `TooltipTrigger`, `TooltipPortal`, `TooltipContent` |
+| | Hover card | `HoverCardRoot`, `HoverCardTrigger`, `HoverCardPortal`, `HoverCardContent` |
+| | Menu | `DropdownMenuRoot`, `DropdownMenuTrigger`, `DropdownMenuContent`, `DropdownMenuItem`, `DropdownMenuCheckboxItem`, `DropdownMenuRadioGroup`, `DropdownMenuRadioItem`, `DropdownMenuItemIndicator`, `DropdownMenuLabel`, `DropdownMenuGroup`, `DropdownMenuSeparator`, `ContextMenuTrigger` |
+| | Navigation menu | `NavigationMenuRoot`, `NavigationMenuList`, `NavigationMenuItem`, `NavigationMenuTrigger`, `NavigationMenuContent`, `NavigationMenuLink` |
+| | Toast | `ToastViewport`, `ToastRoot`, `ToastTitle`, `ToastDescription`, `ToastAction`, `ToastClose`, plus `toast()` |
+| Choice | Checkbox, Switch | `CheckboxRoot`, `CheckboxIndicator`, `SwitchRoot`, `SwitchThumb` |
+| | Radio group | `RadioGroupRoot`, `RadioGroupItem`, `RadioGroupIndicator` |
+| | Toggle, toggle group | `ToggleRoot`, `ToggleGroupRoot`, `ToggleGroupItem` |
+| | Select | `SelectRoot`, `SelectTrigger`, `SelectValue`, `SelectContent`, `SelectItem`, `SelectItemText`, `SelectItemIndicator`, `SelectGroup`, `SelectLabel`, `SelectSeparator` |
+| | Combobox | `ComboboxRoot`, `ComboboxAnchor`, `ComboboxInput`, `ComboboxTrigger`, `ComboboxClear`, `ComboboxContent`, `ComboboxItem`, `ComboboxItemIndicator`, `ComboboxEmpty` |
+| | Command palette | `CommandRoot`, `CommandInput`, `CommandList`, `CommandGroup`, `CommandItem`, `CommandEmpty`, `CommandSeparator` |
+| | Emoji picker | `EmojiPickerRoot`, `EmojiPickerSearch`, `EmojiPickerList`, `EmojiPickerGroup`, `EmojiPickerItem`, `EmojiPickerNav`… |
+| Input | Slider | `SliderRoot`, `SliderTrack`, `SliderRange`, `SliderThumb` |
+| | Number field | `NumberFieldRoot`, `NumberFieldInput`, `NumberFieldIncrement`, `NumberFieldDecrement` |
+| | PIN input | `PinInputRoot`, `PinInputInput` |
+| | Calendar | `CalendarRoot`, `CalendarHeading`, `CalendarPrev`, `CalendarNext`, `CalendarGrid`, `CalendarHeadCell`, `CalendarCell`, `CalendarDay` |
+| Layout | Splitter | `SplitterGroup`, `SplitterPanel`, `SplitterHandle` |
+| | Tree | `TreeRoot`, `TreeItem`, `TreeGroup` |
+| | Carousel | `CarouselRoot`, `CarouselViewport`, `CarouselSlide`, `CarouselPrevious`, `CarouselNext`, `CarouselIndicators`, `CarouselIndicator` |
+| | Sortable | `SortableRoot`, `SortableItem`, `SortableHandle` |
+| Display | Avatar, Progress | `AvatarRoot`, `AvatarImage`, `AvatarFallback`, `ProgressRoot`, `ProgressIndicator` |
+
+Composables: `useDataTable`, `useVirtualList`, `useInView`, `useScrollEdges`,
+`useActiveSection`, `useClipboard`, plus the building blocks below.
+
+The package is `sideEffects: false`. An app importing only `DialogRoot` ships
+no menu, select or table code, and a test enforces this.
+
+## Shared conventions
+
+- **`as` and `asChild`.** Every part renders a sensible element and takes `as`
+  to change it. With `asChild`, the part renders your single child instead,
+  merging its attributes and handlers in.
+- **Controlled or not.** Leave `v-model` off and the component owns its state.
+  Bind it and your value is the source of truth. Every accepted change is
+  emitted, and setting a model to `undefined` clears it.
+- **Your ids are respected.** Give any part an `id` and the ARIA references
+  elsewhere follow it.
+- **Exit animations play.** Closing content stays mounted, with
+  `data-state="closed"`, until its CSS animation ends. With no animation, or
+  reduced motion, it unmounts at once.
+- **Hydration-safe portals.** Overlays teleport only after mount, so server and
+  client renders always agree.
+- **Cancellable dismissal.** Overlays emit `escapeKeyDown` and
+  `pointerDownOutside` (Dialog also `focusOutside`) before closing. Call
+  `event.preventDefault()` to keep them open.
+
+## Lovince-specific behaviour
+
+Two behaviours differ from the Doitrix components these were ported from:
+
+- **Disclosure content and tab panels stay in the DOM** with `hidden` while
+  closed, so find-in-page and `aria-controls` keep working.
+- **Tabs select the first enabled tab** when no value is given, including during
+  server rendering.
+
+Modal dialogs also make the rest of the page `inert`, not just focus-trapped.
+
+## Building blocks
+
+Every component in this package is built the same way:
+
+```ts
+const machine = useMachine(dialogMachine, initialContext, {
+  controlled: { open: () => props.open },          // a v-model, synced in
+  onChange: (next, previous) => emit(…),           // accepted changes, never echoes of props
+  beforeSend: dismiss.filter,                      // e.g. cancellable dismissal
+})
+const api = computed(() => connectDialog(machine.snapshot.value, machine.send))
+// h(Primitive, normalizeProps(api.value.contentProps), slots)
+```
+
+- `useMachine` starts effects on mount (none on the server), stops them on
+  unmount, keeps a controlled value the source of truth, and provides the
+  `query` that `connect` reads the page through. Components never touch the
+  DOM themselves.
+- `normalizeProps` turns the engine's neutral props (`onKeyDown`) into Vue's
+  (`onKeydown`). A React adapter would ship its own, against the same machines.
+- `useListEnv` reads a list's items from the DOM, in visual order, for machines
+  that navigate lists.
+- `Primitive`, `Slot`, `Portal`, `usePresence`, `useIdWatch` handle
+  rendering concerns: `as`/`asChild`, hydration-safe portals, exit animations,
+  consumer ids.
+
+## State attributes
+
+| Attribute | Values |
+|---|---|
+| `data-state` | `open` / `closed`, `checked` / `unchecked` / `indeterminate`, `active` / `inactive` |
+| `data-disabled`, `data-readonly` | present when set |
+| `data-orientation` | `horizontal` / `vertical` |
+| `data-side`, `data-align` | where floating content was placed after collision handling |
+
+Floating content carries `data-anchor-hidden` while its anchor is scrolled out
+of view, and exposes `--lovince-floating-available-height`,
+`--lovince-floating-available-width` and `--lovince-anchor-width`. Disclosure
+content exposes `--lovince-collapsible-height` and `-width` for height animations.
+
+## Known limitations
+
+- Positioning is the engine's own (see [`@lovince/ui-headless`](../ui-headless#positioning)):
+  it respects scrolling containers and transformed ancestors, and hides content
+  whose anchor has scrolled away (`data-anchor-hidden`). Arrows are not built in.
+- See [`@lovince/ui-dom`](../ui-dom#known-limitations) for `inert` and scroll-lock browser caveats.
+
+## License
+
+MIT

package/dist/components/accordion.d.ts

@@ -0,0 +1,197 @@
+import { PropType } from 'vue';
+import { AccordionType } from '@lovince/ui-headless';
+export type { AccordionType };
+/**
+ * Stacked disclosures. `single` keeps at most one open (`v-model` is a string);
+ * `multiple` lets any number open (`v-model` is an array).
+ */
+export declare const AccordionRoot: import('vue').DefineComponent<import('vue').ExtractPropTypes<{
+    type: {
+        type: PropType<AccordionType>;
+        default: string;
+    };
+    modelValue: {
+        type: PropType<string | string[]>;
+        default: undefined;
+    };
+    defaultValue: {
+        type: PropType<string | string[]>;
+        default: undefined;
+    };
+    /** Single mode only: let the open item close, leaving none open. */
+    collapsible: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    disabled: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    as: {
+        readonly type: PropType<string | import('vue').Component>;
+        readonly default: "div";
+    };
+    asChild: {
+        readonly type: BooleanConstructor;
+        readonly default: false;
+    };
+}>, () => import('vue').VNode<import('vue').RendererNode, import('vue').RendererElement, {
+    [key: string]: any;
+}>, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
+    'update:modelValue': (value: string | string[] | undefined) => boolean;
+}, string, import('vue').PublicProps, Readonly<import('vue').ExtractPropTypes<{
+    type: {
+        type: PropType<AccordionType>;
+        default: string;
+    };
+    modelValue: {
+        type: PropType<string | string[]>;
+        default: undefined;
+    };
+    defaultValue: {
+        type: PropType<string | string[]>;
+        default: undefined;
+    };
+    /** Single mode only: let the open item close, leaving none open. */
+    collapsible: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    disabled: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    as: {
+        readonly type: PropType<string | import('vue').Component>;
+        readonly default: "div";
+    };
+    asChild: {
+        readonly type: BooleanConstructor;
+        readonly default: false;
+    };
+}>> & Readonly<{
+    "onUpdate:modelValue"?: ((value: string | string[] | undefined) => any) | undefined;
+}>, {
+    as: string | import('vue').Component;
+    asChild: boolean;
+    type: AccordionType;
+    disabled: boolean;
+    collapsible: boolean;
+    modelValue: string | string[];
+    defaultValue: string | string[];
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, true, {}, any>;
+/** Each item is a disclosure, controlled by the accordion's machine. */
+export declare const AccordionItem: import('vue').DefineComponent<import('vue').ExtractPropTypes<{
+    value: {
+        type: StringConstructor;
+        required: true;
+    };
+    disabled: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    as: {
+        readonly type: PropType<string | import('vue').Component>;
+        readonly default: "div";
+    };
+    asChild: {
+        readonly type: BooleanConstructor;
+        readonly default: false;
+    };
+}>, () => import('vue').VNode<import('vue').RendererNode, import('vue').RendererElement, {
+    [key: string]: any;
+}>, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<import('vue').ExtractPropTypes<{
+    value: {
+        type: StringConstructor;
+        required: true;
+    };
+    disabled: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    as: {
+        readonly type: PropType<string | import('vue').Component>;
+        readonly default: "div";
+    };
+    asChild: {
+        readonly type: BooleanConstructor;
+        readonly default: false;
+    };
+}>> & Readonly<{}>, {
+    as: string | import('vue').Component;
+    asChild: boolean;
+    disabled: boolean;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, true, {}, any>;
+export declare const AccordionHeader: import('vue').DefineComponent<import('vue').ExtractPropTypes<{
+    as: {
+        default: string;
+        type: PropType<string | import('vue').Component>;
+    };
+    asChild: {
+        readonly type: BooleanConstructor;
+        readonly default: false;
+    };
+}>, () => import('vue').VNode<import('vue').RendererNode, import('vue').RendererElement, {
+    [key: string]: any;
+}>, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<import('vue').ExtractPropTypes<{
+    as: {
+        default: string;
+        type: PropType<string | import('vue').Component>;
+    };
+    asChild: {
+        readonly type: BooleanConstructor;
+        readonly default: false;
+    };
+}>> & Readonly<{}>, {
+    as: string | import('vue').Component;
+    asChild: boolean;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, true, {}, any>;
+/** Arrow keys move between the headers; Home and End go to the first and last. */
+export declare const AccordionTrigger: import('vue').DefineComponent<import('vue').ExtractPropTypes<{
+    as: {
+        default: string;
+        type: PropType<string | import('vue').Component>;
+    };
+    asChild: {
+        readonly type: BooleanConstructor;
+        readonly default: false;
+    };
+}>, () => import('vue').VNode<import('vue').RendererNode, import('vue').RendererElement, {
+    [key: string]: any;
+}>, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<import('vue').ExtractPropTypes<{
+    as: {
+        default: string;
+        type: PropType<string | import('vue').Component>;
+    };
+    asChild: {
+        readonly type: BooleanConstructor;
+        readonly default: false;
+    };
+}>> & Readonly<{}>, {
+    as: string | import('vue').Component;
+    asChild: boolean;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, true, {}, any>;
+export declare const AccordionContent: import('vue').DefineComponent<import('vue').ExtractPropTypes<{
+    readonly as: {
+        readonly type: PropType<string | import('vue').Component>;
+        readonly default: "div";
+    };
+    readonly asChild: {
+        readonly type: BooleanConstructor;
+        readonly default: false;
+    };
+}>, () => import('vue').VNode<import('vue').RendererNode, import('vue').RendererElement, {
+    [key: string]: any;
+}>, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<import('vue').ExtractPropTypes<{
+    readonly as: {
+        readonly type: PropType<string | import('vue').Component>;
+        readonly default: "div";
+    };
+    readonly asChild: {
+        readonly type: BooleanConstructor;
+        readonly default: false;
+    };
+}>> & Readonly<{}>, {
+    readonly as: string | import('vue').Component;
+    readonly asChild: boolean;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, true, {}, any>;

package/dist/components/avatar.d.ts

@@ -0,0 +1,90 @@
+import { ImageStatus } from '@lovince/ui-headless';
+export type { ImageStatus };
+export declare const AvatarRoot: import('vue').DefineComponent<import('vue').ExtractPropTypes<{
+    as: {
+        default: string;
+        type: import('vue').PropType<string | import('vue').Component>;
+    };
+    asChild: {
+        readonly type: BooleanConstructor;
+        readonly default: false;
+    };
+}>, () => import('vue').VNode<import('vue').RendererNode, import('vue').RendererElement, {
+    [key: string]: any;
+}>, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<import('vue').ExtractPropTypes<{
+    as: {
+        default: string;
+        type: import('vue').PropType<string | import('vue').Component>;
+    };
+    asChild: {
+        readonly type: BooleanConstructor;
+        readonly default: false;
+    };
+}>> & Readonly<{}>, {
+    as: string | import('vue').Component;
+    asChild: boolean;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, true, {}, any>;
+/** Renders only once the machine has seen the image load; the fallback shows until then. */
+export declare const AvatarImage: import('vue').DefineComponent<import('vue').ExtractPropTypes<{
+    src: {
+        type: StringConstructor;
+        default: undefined;
+    };
+    alt: {
+        type: StringConstructor;
+        default: string;
+    };
+}>, () => import('vue').VNode<import('vue').RendererNode, import('vue').RendererElement, {
+    [key: string]: any;
+}> | null, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {
+    status: (status: ImageStatus) => boolean;
+}, string, import('vue').PublicProps, Readonly<import('vue').ExtractPropTypes<{
+    src: {
+        type: StringConstructor;
+        default: undefined;
+    };
+    alt: {
+        type: StringConstructor;
+        default: string;
+    };
+}>> & Readonly<{
+    onStatus?: ((status: ImageStatus) => any) | undefined;
+}>, {
+    src: string;
+    alt: string;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, true, {}, any>;
+export declare const AvatarFallback: import('vue').DefineComponent<import('vue').ExtractPropTypes<{
+    as: {
+        default: string;
+        type: import('vue').PropType<string | import('vue').Component>;
+    };
+    /** Wait before showing, so a fast image does not flash initials first. */
+    delayMs: {
+        type: NumberConstructor;
+        default: number;
+    };
+    asChild: {
+        readonly type: BooleanConstructor;
+        readonly default: false;
+    };
+}>, () => import('vue').VNode<import('vue').RendererNode, import('vue').RendererElement, {
+    [key: string]: any;
+}> | null, {}, {}, {}, import('vue').ComponentOptionsMixin, import('vue').ComponentOptionsMixin, {}, string, import('vue').PublicProps, Readonly<import('vue').ExtractPropTypes<{
+    as: {
+        default: string;
+        type: import('vue').PropType<string | import('vue').Component>;
+    };
+    /** Wait before showing, so a fast image does not flash initials first. */
+    delayMs: {
+        type: NumberConstructor;
+        default: number;
+    };
+    asChild: {
+        readonly type: BooleanConstructor;
+        readonly default: false;
+    };
+}>> & Readonly<{}>, {
+    as: string | import('vue').Component;
+    asChild: boolean;
+    delayMs: number;
+}, {}, {}, {}, string, import('vue').ComponentProvideOptions, true, {}, any>;