@ternent/core 0.0.1

package/packages/ui/src/primitives/Input/Input.props.ts

@@ -0,0 +1,29 @@
+import type { PropType } from "vue";
+import type { InputSize, InputType } from "./Input.types";
+
+export const inputProps = {
+  modelValue: {
+    type: [String, Number],
+    default: "",
+  },
+  type: {
+    type: String as PropType<InputType>,
+    default: "text",
+  },
+  size: {
+    type: String as PropType<InputSize>,
+    default: "md",
+  },
+  disabled: {
+    type: Boolean,
+    default: false,
+  },
+  invalid: {
+    type: Boolean,
+    default: false,
+  },
+  readonly: {
+    type: Boolean,
+    default: false,
+  },
+};

package/packages/ui/src/primitives/Input/Input.spec.md

@@ -0,0 +1,79 @@
+# Input
+
+## Purpose
+
+Single-line text entry primitive for the v2 form system.
+
+## Category
+
+Primitive
+
+## Anatomy
+
+- input root
+- optional `leading` adornment slot
+- optional `trailing` adornment slot
+
+## Public API
+
+Props:
+
+- `modelValue`: string or number
+- `type`: `text | email | password | search | url | tel | number`
+- `size`: `sm | md | lg`
+- `disabled`: boolean
+- `invalid`: boolean
+- `readonly`: boolean
+
+Slots:
+
+- `leading`
+- `trailing`
+
+Events:
+
+- `update:modelValue`
+- `focus`
+- `blur`
+
+## States
+
+- default
+- hover
+- focus-visible
+- disabled
+- invalid
+- readonly
+
+## Accessibility
+
+- uses native `<input>` semantics
+- supports `aria-invalid` when invalid
+- relies on external labels and descriptions through attrs such as `id` and `aria-describedby`
+
+## Token usage
+
+- `--ui-surface`
+- `--ui-fg`
+- `--ui-fg-muted`
+- `--ui-border`
+- `--ui-primary`
+- `--ui-critical`
+- `--ui-ring`
+- `--ui-radius-md`
+- `--ui-duration-normal`
+- `--ui-ease-out`
+
+## Examples
+
+```vue
+<Input v-model="email" type="email" />
+```
+
+```vue
+<Input v-model="query" invalid aria-describedby="search-message">
+  <template #leading>
+    <IconSearch />
+  </template>
+</Input>
+```

package/packages/ui/src/primitives/Input/Input.types.ts

@@ -0,0 +1,13 @@
+export const inputSizeValues = ["sm", "md", "lg"] as const;
+export const inputTypeValues = [
+  "text",
+  "email",
+  "password",
+  "search",
+  "url",
+  "tel",
+  "number",
+] as const;
+
+export type InputSize = (typeof inputSizeValues)[number];
+export type InputType = (typeof inputTypeValues)[number];

package/packages/ui/src/primitives/Input/Input.variants.ts

@@ -0,0 +1,54 @@
+import type { InputSize } from "./Input.types";
+
+export const inputWrapperClass = "relative w-full";
+
+export const inputBaseClass =
+  "flex w-full appearance-none items-center border bg-[var(--ui-surface)] " +
+  "text-[var(--ui-fg)] placeholder:text-[var(--ui-fg-muted)] " +
+  "transition-[box-shadow,border-color,background-color,color] " +
+  "duration-[var(--ui-duration-normal)] ease-[var(--ui-ease-out)] " +
+  "rounded-[var(--ui-radius-md)] border-[var(--ui-border)] " +
+  "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--ui-ring)] focus-visible:border-[var(--ui-primary)] " +
+  "disabled:pointer-events-none disabled:cursor-not-allowed disabled:opacity-50 " +
+  "read-only:cursor-default read-only:bg-[var(--ui-tonal-tertiary)]";
+
+export const inputStateClasses = {
+  default: "hover:border-[var(--ui-primary-muted)]",
+  invalid:
+    "border-[var(--ui-critical)] text-[var(--ui-fg)] " +
+    "focus-visible:border-[var(--ui-critical)] focus-visible:ring-[var(--ui-critical-muted)]",
+} as const;
+
+export const inputSizeClasses: Record<InputSize, string> = {
+  sm: "h-9 px-3 text-sm",
+  md: "h-10 px-4 text-sm",
+  lg: "h-11 px-4 text-base",
+};
+
+export const inputPaddingWithLeading: Record<InputSize, string> = {
+  sm: "pl-9",
+  md: "pl-10",
+  lg: "pl-11",
+};
+
+export const inputPaddingWithTrailing: Record<InputSize, string> = {
+  sm: "pr-9",
+  md: "pr-10",
+  lg: "pr-11",
+};
+
+export const inputAdornmentBaseClass =
+  "pointer-events-none absolute top-1/2 inline-flex -translate-y-1/2 items-center justify-center text-[var(--ui-fg-muted)]";
+
+export const inputAdornmentPositionClasses = {
+  leading: {
+    sm: "left-3 size-4",
+    md: "left-3 size-4",
+    lg: "left-4 size-5",
+  },
+  trailing: {
+    sm: "right-3 size-4",
+    md: "right-3 size-4",
+    lg: "right-4 size-5",
+  },
+} as const;

package/packages/ui/src/primitives/Input/Input.vue

@@ -0,0 +1,99 @@
+<script setup lang="ts">
+import { computed, normalizeClass, useAttrs, useSlots } from "vue";
+import { twMerge } from "tailwind-merge";
+import { inputProps } from "./Input.props";
+import {
+  inputAdornmentBaseClass,
+  inputAdornmentPositionClasses,
+  inputBaseClass,
+  inputPaddingWithLeading,
+  inputPaddingWithTrailing,
+  inputSizeClasses,
+  inputStateClasses,
+  inputWrapperClass,
+} from "./Input.variants";
+
+defineOptions({ inheritAttrs: false });
+
+const emit = defineEmits<{
+  "update:modelValue": [value: string];
+  blur: [event: FocusEvent];
+  focus: [event: FocusEvent];
+}>();
+
+const attrs = useAttrs();
+const props = defineProps(inputProps);
+const slots = useSlots();
+
+const hasLeading = computed(() => Boolean(slots.leading));
+const hasTrailing = computed(() => Boolean(slots.trailing));
+
+const classes = computed(() =>
+  twMerge(
+    inputBaseClass,
+    inputSizeClasses[props.size],
+    props.invalid ? inputStateClasses.invalid : inputStateClasses.default,
+    hasLeading.value ? inputPaddingWithLeading[props.size] : "",
+    hasTrailing.value ? inputPaddingWithTrailing[props.size] : "",
+    normalizeClass(attrs.class),
+  ),
+);
+
+const inputAttrs = computed(() => {
+  const {
+    class: _class,
+    value: _value,
+    modelValue: _modelValue,
+    type: _type,
+    disabled: _disabled,
+    readonly: _readonly,
+    ...rest
+  } = attrs;
+
+  return rest;
+});
+
+function handleInput(event: Event) {
+  emit("update:modelValue", (event.target as HTMLInputElement).value);
+}
+
+function handleFocus(event: FocusEvent) {
+  emit("focus", event);
+}
+
+function handleBlur(event: FocusEvent) {
+  emit("blur", event);
+}
+</script>
+
+<template>
+  <div :class="inputWrapperClass">
+    <span
+      v-if="$slots.leading"
+      :class="[inputAdornmentBaseClass, inputAdornmentPositionClasses.leading[props.size]]"
+      aria-hidden="true"
+    >
+      <slot name="leading" />
+    </span>
+    <input
+      :value="props.modelValue"
+      :type="props.type"
+      :class="classes"
+      :disabled="props.disabled"
+      :readonly="props.readonly"
+      :aria-invalid="props.invalid ? 'true' : undefined"
+      :data-invalid="props.invalid ? 'true' : 'false'"
+      v-bind="inputAttrs"
+      @input="handleInput"
+      @focus="handleFocus"
+      @blur="handleBlur"
+    />
+    <span
+      v-if="$slots.trailing"
+      :class="[inputAdornmentBaseClass, inputAdornmentPositionClasses.trailing[props.size]]"
+      aria-hidden="true"
+    >
+      <slot name="trailing" />
+    </span>
+  </div>
+</template>

package/packages/ui/src/primitives/Label/Label.props.ts

@@ -0,0 +1,25 @@
+import type { PropType } from "vue";
+import type { LabelSize } from "./Label.types";
+
+export const labelProps = {
+  for: {
+    type: String,
+    default: undefined,
+  },
+  size: {
+    type: String as PropType<LabelSize>,
+    default: "md",
+  },
+  required: {
+    type: Boolean,
+    default: false,
+  },
+  disabled: {
+    type: Boolean,
+    default: false,
+  },
+  invalid: {
+    type: Boolean,
+    default: false,
+  },
+};

package/packages/ui/src/primitives/Label/Label.spec.md

@@ -0,0 +1,31 @@
+# Label
+
+## Purpose
+
+Shared field label primitive for form controls and field patterns.
+
+## Category
+
+Primitive
+
+## Public API
+
+Props:
+
+- `for`: string
+- `size`: `sm | md | lg`
+- `required`: boolean
+- `disabled`: boolean
+- `invalid`: boolean
+
+## Accessibility
+
+- uses native `<label>` semantics
+- supports `for` linkage to form controls
+- required indicator is visual only; field semantics should still be applied to the control itself
+
+## Examples
+
+```vue
+<Label for="email" required>Email address</Label>
+```

package/packages/ui/src/primitives/Label/Label.types.ts

@@ -0,0 +1,3 @@
+export const labelSizeValues = ["sm", "md", "lg"] as const;
+
+export type LabelSize = (typeof labelSizeValues)[number];

package/packages/ui/src/primitives/Label/Label.variants.ts

@@ -0,0 +1,17 @@
+import type { LabelSize } from "./Label.types";
+
+export const labelBaseClass = "inline-flex items-center gap-1 font-medium text-[var(--ui-fg)]";
+
+export const labelStateClasses = {
+  default: "",
+  disabled: "opacity-50",
+  invalid: "text-[var(--ui-critical)]",
+} as const;
+
+export const labelSizeClasses: Record<LabelSize, string> = {
+  sm: "text-xs",
+  md: "text-sm",
+  lg: "text-base",
+};
+
+export const labelRequiredClass = "text-[var(--ui-critical)]";

package/packages/ui/src/primitives/Label/Label.vue

@@ -0,0 +1,38 @@
+<script setup lang="ts">
+import { computed, normalizeClass, useAttrs } from "vue";
+import { twMerge } from "tailwind-merge";
+import { labelProps } from "./Label.props";
+import {
+  labelBaseClass,
+  labelRequiredClass,
+  labelSizeClasses,
+  labelStateClasses,
+} from "./Label.variants";
+
+defineOptions({ inheritAttrs: false });
+
+const attrs = useAttrs();
+const props = defineProps(labelProps);
+
+const classes = computed(() =>
+  twMerge(
+    labelBaseClass,
+    labelSizeClasses[props.size],
+    props.disabled ? labelStateClasses.disabled : "",
+    props.invalid ? labelStateClasses.invalid : labelStateClasses.default,
+    normalizeClass(attrs.class),
+  ),
+);
+
+const labelAttrs = computed(() => {
+  const { class: _class, ...rest } = attrs;
+  return rest;
+});
+</script>
+
+<template>
+  <label :for="props.for" :class="classes" v-bind="labelAttrs">
+    <slot />
+    <span v-if="props.required" :class="labelRequiredClass" aria-hidden="true">*</span>
+  </label>
+</template>

package/packages/ui/src/primitives/Menu/Menu.props.ts

@@ -0,0 +1,17 @@
+import type { PropType } from "vue";
+import type { MenuItem, MenuPlacement } from "./Menu.types";
+
+export const menuProps = {
+  items: {
+    type: Array as PropType<MenuItem[]>,
+    default: () => [],
+  },
+  placement: {
+    type: String as PropType<MenuPlacement>,
+    default: "bottom",
+  },
+  showArrow: {
+    type: Boolean,
+    default: true,
+  },
+};

package/packages/ui/src/primitives/Menu/Menu.spec.md

@@ -0,0 +1,38 @@
+# Menu
+
+## Purpose
+
+Anchored action list primitive for command and option selection.
+
+## Category
+
+Primitive
+
+## Public API
+
+Props:
+
+- `open` via `v-model:open`
+- `items`: `{ value?, label?, disabled?, type?: 'item' | 'separator' }[]`
+- `placement`: `top | bottom | left | right`
+- `showArrow`
+
+Slots:
+
+- `trigger`
+- `item`
+
+Events:
+
+- `select`
+
+## Accessibility
+
+- built on Ark menu semantics
+- keyboard navigation and dismiss behavior come from Ark
+
+## Keyboard behavior
+
+- arrow keys move between items
+- Enter/Space select the highlighted item
+- Escape closes the menu

package/packages/ui/src/primitives/Menu/Menu.types.ts

@@ -0,0 +1,10 @@
+export const menuPlacementValues = ["top", "bottom", "left", "right"] as const;
+
+export type MenuPlacement = (typeof menuPlacementValues)[number];
+
+export type MenuItem = {
+  disabled?: boolean;
+  label?: string;
+  type?: "item" | "separator";
+  value?: string;
+};

package/packages/ui/src/primitives/Menu/Menu.variants.ts

@@ -0,0 +1,10 @@
+export const menuPositionerClass = "z-50 px-2";
+export const menuContentClass =
+  "min-w-48 rounded-[var(--ui-radius-lg)] border border-[var(--ui-border)] bg-[var(--ui-surface)] p-1 text-[var(--ui-fg)] shadow-[var(--ui-shadow-md)]";
+export const menuArrowClass = "fill-[var(--ui-surface)] stroke-[var(--ui-border)] stroke-1";
+export const menuItemClass =
+  "flex w-full items-center rounded-[var(--ui-radius-sm)] px-3 py-2 text-sm text-[var(--ui-fg)] " +
+  "transition-[background-color,color] duration-[var(--ui-duration-normal)] ease-[var(--ui-ease-out)] " +
+  "hover:bg-[var(--ui-tonal-secondary)] focus-visible:outline-none data-[highlighted]:bg-[var(--ui-tonal-secondary)] data-[highlighted]:text-[var(--ui-fg)] " +
+  "data-[disabled]:pointer-events-none data-[disabled]:opacity-50";
+export const menuSeparatorClass = "my-1 h-px bg-[var(--ui-border)]";

package/packages/ui/src/primitives/Menu/Menu.vue

@@ -0,0 +1,57 @@
+<script setup lang="ts">
+import { Menu as ArkMenu } from "@ark-ui/vue/menu";
+import { menuProps } from "./Menu.props";
+import {
+  menuArrowClass,
+  menuContentClass,
+  menuItemClass,
+  menuPositionerClass,
+  menuSeparatorClass,
+} from "./Menu.variants";
+import type { MenuItem } from "./Menu.types";
+
+const emit = defineEmits<{
+  select: [item: MenuItem];
+}>();
+
+const open = defineModel<boolean>("open", { default: false });
+const props = defineProps(menuProps);
+
+function handleSelect(item: MenuItem) {
+  emit("select", item);
+}
+</script>
+
+<template>
+  <ArkMenu.Root
+    v-model:open="open"
+    :positioning="{ placement: props.placement }"
+    lazy-mount
+    unmount-on-exit
+  >
+    <ArkMenu.Trigger v-if="$slots.trigger" as-child>
+      <slot name="trigger" />
+    </ArkMenu.Trigger>
+    <ArkMenu.Positioner :class="menuPositionerClass">
+      <ArkMenu.Content :class="menuContentClass">
+        <ArkMenu.Arrow v-if="props.showArrow" :class="menuArrowClass">
+          <ArkMenu.ArrowTip />
+        </ArkMenu.Arrow>
+        <template v-for="(item, index) in props.items" :key="item.value ?? `separator-${index}`">
+          <ArkMenu.Separator v-if="item.type === 'separator'" :class="menuSeparatorClass" />
+          <ArkMenu.Item
+            v-else
+            :value="item.value ?? item.label ?? `item-${index}`"
+            :disabled="item.disabled"
+            :class="menuItemClass"
+            @select="handleSelect(item)"
+          >
+            <slot name="item" :item="item">
+              {{ item.label }}
+            </slot>
+          </ArkMenu.Item>
+        </template>
+      </ArkMenu.Content>
+    </ArkMenu.Positioner>
+  </ArkMenu.Root>
+</template>

package/packages/ui/src/primitives/Popover/Popover.props.ts

@@ -0,0 +1,25 @@
+import type { PropType } from "vue";
+import type { PopoverPlacement } from "./Popover.types";
+
+export const popoverProps = {
+  title: {
+    type: String,
+    default: undefined,
+  },
+  description: {
+    type: String,
+    default: undefined,
+  },
+  placement: {
+    type: String as PropType<PopoverPlacement>,
+    default: "bottom",
+  },
+  showArrow: {
+    type: Boolean,
+    default: true,
+  },
+  showClose: {
+    type: Boolean,
+    default: false,
+  },
+};

package/packages/ui/src/primitives/Popover/Popover.spec.md

@@ -0,0 +1,49 @@
+# Popover
+
+## Purpose
+
+Anchored overlay primitive for non-modal contextual content.
+
+## Category
+
+Primitive
+
+## Public API
+
+Props:
+
+- `open` via `v-model:open`
+- `title`
+- `description`
+- `placement`: `top | bottom | left | right`
+- `showArrow`
+- `showClose`
+
+Slots:
+
+- `trigger`
+- `header`
+- default content
+- `footer`
+
+## Accessibility
+
+- built on Ark popover semantics
+- supports anchored positioning and dismiss behavior
+- title and description are wired when provided
+
+## Keyboard behavior
+
+- trigger remains the anchor point
+- Escape closes the popover
+
+## Example
+
+```vue
+<Popover title="Shortcuts">
+  <template #trigger>
+    <Button variant="plain-secondary">Help</Button>
+  </template>
+  Press <kbd>?</kbd> to open the command menu.
+</Popover>
+```

package/packages/ui/src/primitives/Popover/Popover.types.ts

@@ -0,0 +1,3 @@
+export const popoverPlacementValues = ["top", "bottom", "left", "right"] as const;
+
+export type PopoverPlacement = (typeof popoverPlacementValues)[number];

package/packages/ui/src/primitives/Popover/Popover.variants.ts

@@ -0,0 +1,18 @@
+export const popoverPositionerClass = "z-50 px-2";
+export const popoverContentClass =
+  "w-full min-w-56 max-w-sm rounded-[var(--ui-radius-lg)] border border-[var(--ui-border)] " +
+  "bg-[var(--ui-surface)] text-[var(--ui-fg)] shadow-[var(--ui-shadow-md)] " +
+  "focus-visible:outline-none";
+export const popoverHeaderClass =
+  "flex items-start justify-between gap-3 border-b border-[var(--ui-border)] px-4 py-3";
+export const popoverTitleClass = "text-sm font-semibold text-[var(--ui-fg)]";
+export const popoverDescriptionClass = "mt-1 text-sm text-[var(--ui-fg-muted)]";
+export const popoverBodyClass = "px-4 py-3";
+export const popoverFooterClass =
+  "flex items-center justify-end gap-3 border-t border-[var(--ui-border)] px-4 py-3";
+export const popoverCloseClass =
+  "inline-flex size-8 items-center justify-center rounded-[var(--ui-radius-sm)] border border-[var(--ui-border)] " +
+  "text-[var(--ui-fg-muted)] transition-[border-color,background-color,color] duration-[var(--ui-duration-normal)] ease-[var(--ui-ease-out)] " +
+  "hover:border-[var(--ui-primary-muted)] hover:bg-[var(--ui-tonal-secondary)] hover:text-[var(--ui-fg)] " +
+  "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--ui-ring)]";
+export const popoverArrowClass = "fill-[var(--ui-surface)] stroke-[var(--ui-border)] stroke-1";