@pienter/ui 0.2.0 → 0.5.0

package/utils/navigation/sidebar.ts

@@ -0,0 +1,97 @@
+/**
+ * Sidebar primitives, applied reactively by Sidebar.vue. See ADR 0007.
+ */
+
+/** A group's expanded/flyout state, as the templates render it. */
+export type SubmenuState = 'open' | 'closed';
+
+/** Grace period before an unpinned flyout closes on pointer-out. */
+export const SUBMENU_CLOSE_DELAY = 140;
+
+/**
+ * Hierarchical-href match — locked algorithm. Returns true when
+ * `itemHref` is the prefix of `activeHref` honoring path boundaries.
+ *
+ * - `/` (root) is special-cased to strict equality so it doesn't
+ *   greedily match every URL.
+ * - Substring-only matches are rejected (`/admin/members-old` does
+ *   NOT match `/admin/members`).
+ *
+ * See CONVENTIONS.md § Active-href hierarchical-match algorithm.
+ */
+export function isHrefActive(
+    activeHref: string | null | undefined,
+    itemHref: string,
+): boolean {
+    if (!activeHref) return false;
+    if (itemHref === '/') return activeHref === '/';
+    if (activeHref === itemHref) return true;
+    return activeHref.startsWith(itemHref + '/');
+}
+
+/** Kebab-case slug used as a group's key when none was supplied. */
+export function deriveGroupKey(label: string): string {
+    return label
+        .normalize('NFKD')
+        .replace(/[̀-ͯ]/g, '')
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+}
+
+/** Viewport coordinates for a collapsed-rail flyout. */
+export interface SubmenuPosition {
+    left: number;
+    top: number;
+    height: number;
+}
+
+/**
+ * Where a collapsed rail's flyout sits: flush with the rail, starting below
+ * the brand if there is one, running the column's full height. Physical
+ * `left` because RTL is deferred library-wide.
+ */
+export function computeSubmenuPosition(
+    railRect: DOMRect,
+    brandRect: DOMRect | null,
+): SubmenuPosition {
+    const top = brandRect ? brandRect.bottom : railRect.top;
+    return {
+        left: railRect.right,
+        top,
+        height: Math.max(0, railRect.bottom - top),
+    };
+}
+
+/** Below the drawer breakpoint there is no rail, so no flyouts. */
+export function isSubmenuActive(options: {
+    policy: 'hidden' | 'panel';
+    collapsed: boolean;
+    viewportWidth: number;
+    drawerBreakpoint: number;
+}): boolean {
+    return (
+        options.policy === 'panel' &&
+        options.collapsed &&
+        options.viewportWidth >= options.drawerBreakpoint
+    );
+}
+
+/** Whether a group's subtree contains the current page. */
+export function groupContainsActive(
+    items: readonly SidebarItemLike[],
+    activeHref: string | null | undefined,
+): boolean {
+    return items.some((item) => {
+        if (item.type === 'link') return isHrefActive(activeHref, item.href);
+        if (item.type === 'group')
+            return groupContainsActive(item.items, activeHref);
+        return false;
+    });
+}
+
+/** The part of `SidebarItem` these primitives read; avoids a component import. */
+export type SidebarItemLike =
+    | { type: 'link'; href: string }
+    | { type: 'group'; items: readonly SidebarItemLike[] }
+    | { type: 'section' };

package/utils/validation/form.ts

@@ -1,13 +1,10 @@
 import { type Validator, validate } from './rules.js';
 
 /**
- * Placeholder shape for form-submit responses, consumed identically by both
- * `Form.vue` (reactive orchestration) and `controllers/form.ts:mountForm`
- * (Astro imperative orchestration). The symmetry requirement is locked in
- * design D13 / spec "Unified Form Submit Response Handling"; the exact
- * shape is **subject to change when ts-sdk publishes the canonical
- * response shape**, at which point both implementations are updated
- * together.
+ * Placeholder shape for form-submit responses, consumed by `Form.vue`'s
+ * orchestration. Locked in design D13 / spec "Unified Form Submit Response
+ * Handling"; the exact shape is **subject to change when ts-sdk publishes
+ * the canonical response shape**.
  */
 export interface FormSubmitResponse {
     /** Whether the submit succeeded. */
@@ -28,8 +25,8 @@ export interface FormSubmitResponse {
 
 /**
  * Run a per-field validator map against a `FormData` instance and return
- * a `Record<string, string[]>` of field errors. Pure function; framework
- * agnostic. Used by both Vue and Astro Form orchestration.
+ * a `Record<string, string[]>` of field errors. Pure function; used by
+ * Form.vue's orchestration.
  *
  * Field values are read via `formData.get(name)` and coerced to strings.
  * Fields without an entry in `validators` are not checked. Fields whose

package/components/action/button/Button.astro

@@ -1,95 +0,0 @@
----
-import './button.css';
-import Icon from '../../display/icon/Icon.astro';
-import Spinner from '../../feedback/spinner/Spinner.astro';
-import type { IconName } from '../../../icons/index.js';
-
-interface Props {
-  variant?: 'primary' | 'secondary' | 'ghost' | 'danger' | 'link';
-  size?: 'sm' | 'md';
-  disabled?: boolean;
-  loading?: boolean;
-  type?: 'button' | 'submit' | 'reset';
-  block?: boolean;
-  href?: string;
-  /** Leading icon from the shipped set. Use the `icon` slot for a custom <svg>. */
-  icon?: IconName;
-  /** Anchor target, only applied when `href` is set (renders an <a>). */
-  target?: string;
-  /** Anchor rel; defaults to a safe value for `target="_blank"`. */
-  rel?: string;
-  id?: string;
-}
-
-const {
-  variant = 'secondary',
-  size = 'md',
-  disabled = false,
-  loading = false,
-  type = 'button',
-  block = false,
-  href,
-  icon,
-  target,
-  rel,
-  id,
-  ...rest
-} = Astro.props;
-
-const Tag = href ? 'a' : 'button';
-const isInert = disabled || loading;
-// Button tier -> Icon size for the leading glyph (the Spinner is sized in button.css)
-const iconSize = size === 'sm' ? 'sm' : 'md';
-const hasIconSlot = Astro.slots.has('icon');
-const hasIcon = !!icon || hasIconSlot;
-const resolvedRel = href
-  ? (rel ?? (target === '_blank' ? 'noopener noreferrer' : undefined))
-  : undefined;
-
-// the icon slot wins over the `icon` name; flag the redundant combination in dev
-if (import.meta.env.DEV && icon && hasIconSlot) {
-  console.warn(
-    '[pienter-ui] Button received both an `icon` name and an `icon` slot; the slot is used and `icon` is ignored.',
-  );
-}
----
-
-<Tag
-  id={id}
-  class="pui-btn"
-  type={href ? undefined : type}
-  href={href}
-  target={href ? target : undefined}
-  rel={resolvedRel}
-  disabled={href ? undefined : isInert}
-  aria-disabled={href && isInert ? 'true' : undefined}
-  tabindex={href && isInert ? '-1' : undefined}
-  aria-busy={loading ? 'true' : undefined}
-  data-variant={variant}
-  data-size={size}
-  data-block={block ? 'true' : undefined}
-  data-state={loading ? 'loading' : undefined}
-  {...rest}
->
-  {
-    loading && (
-      <span class="pui-btn__spinner" aria-hidden="true">
-        <Spinner />
-      </span>
-    )
-  }
-  {
-    hasIcon && (
-      <span class="pui-btn__icon" aria-hidden="true">
-        {hasIconSlot ? (
-          <Icon size={iconSize}>
-            <slot name="icon" />
-          </Icon>
-        ) : (
-          <Icon name={icon} size={iconSize} />
-        )}
-      </span>
-    )
-  }
-  <span class="pui-btn__label"><slot /></span>
-</Tag>

package/components/action/button/IconButton.astro

@@ -1,86 +0,0 @@
----
-import './button.css';
-import Icon from '../../display/icon/Icon.astro';
-import Spinner from '../../feedback/spinner/Spinner.astro';
-import type { IconName } from '../../../icons/index.js';
-
-interface Props {
-  /** Accessible name for the icon-only control (required — there is no visible label). */
-  label: string;
-  /** Shipped icon to render. Omit and pass your own SVG via the default slot instead. */
-  name?: IconName;
-  variant?: 'primary' | 'secondary' | 'ghost' | 'danger';
-  size?: 'sm' | 'md';
-  disabled?: boolean;
-  loading?: boolean;
-  type?: 'button' | 'submit' | 'reset';
-  href?: string;
-  /** Anchor target, only applied when `href` is set (renders an <a>). */
-  target?: string;
-  /** Anchor rel; defaults to a safe value for `target="_blank"`. */
-  rel?: string;
-  id?: string;
-}
-
-const {
-  label,
-  name,
-  variant = 'secondary',
-  size = 'md',
-  disabled = false,
-  loading = false,
-  type = 'button',
-  href,
-  target,
-  rel,
-  id,
-  ...rest
-} = Astro.props;
-
-const Tag = href ? 'a' : 'button';
-const isInert = disabled || loading;
-const iconSize = size === 'sm' ? 'sm' : 'md';
-const hasSlot = Astro.slots.has('default');
-const resolvedRel = href
-  ? (rel ?? (target === '_blank' ? 'noopener noreferrer' : undefined))
-  : undefined;
-
-// the slot wins over the `name`; flag the redundant combination in dev
-if (import.meta.env.DEV && name && hasSlot) {
-  console.warn(
-    '[pienter-ui] IconButton received both a `name` and slot content; the slot is used and `name` is ignored.',
-  );
-}
----
-
-<Tag
-  id={id}
-  class="pui-icon-btn"
-  type={href ? undefined : type}
-  href={href}
-  target={href ? target : undefined}
-  rel={resolvedRel}
-  disabled={href ? undefined : isInert}
-  aria-disabled={href && isInert ? 'true' : undefined}
-  tabindex={href && isInert ? '-1' : undefined}
-  aria-busy={loading ? 'true' : undefined}
-  aria-label={label}
-  data-variant={variant}
-  data-size={size}
-  data-state={loading ? 'loading' : undefined}
-  {...rest}
->
-  {
-    loading ? (
-      <span class="pui-btn__spinner" aria-hidden="true">
-        <Spinner />
-      </span>
-    ) : hasSlot ? (
-      <Icon size={iconSize}>
-        <slot />
-      </Icon>
-    ) : (
-      <Icon name={name} size={iconSize} />
-    )
-  }
-</Tag>

package/components/display/avatar/Avatar.astro

@@ -1,17 +0,0 @@
----
-import './avatar.css';
-
-interface Props {
-  size?: 'sm' | 'lg';
-  tone?: 'brand' | 'solid';
-  src?: string;
-  alt?: string;
-  initials?: string;
-}
-
-const { size, tone, src, alt = '', initials, ...rest } = Astro.props;
----
-
-<span class="pui-avatar" data-size={size} data-tone={tone} {...rest}>
-  {src ? <img src={src} alt={alt} /> : initials ? initials : <slot />}
-</span>

package/components/display/avatar/AvatarStack.astro

@@ -1,9 +0,0 @@
----
-import './avatar.css';
-
-const { ...rest } = Astro.props;
----
-
-<div class="pui-avatar-stack" {...rest}>
-  <slot />
-</div>

package/components/display/badge/Badge.astro

@@ -1,15 +0,0 @@
----
-import './badge.css';
-
-interface Props {
-  tone?: 'brand' | 'success' | 'warning' | 'danger' | 'solid';
-  dot?: boolean;
-}
-
-const { tone, dot = false, ...rest } = Astro.props;
----
-
-<span class="pui-badge" data-tone={tone} {...rest}>
-  {dot && <span class="pui-badge__dot" />}
-  <slot />
-</span>

package/components/display/empty/Empty.astro

@@ -1,9 +0,0 @@
----
-import './empty.css';
-
-const { ...rest } = Astro.props;
----
-
-<div class="pui-empty" {...rest}>
-  <slot />
-</div>

package/components/display/icon/Icon.astro

@@ -1,52 +0,0 @@
----
-import './icon.css';
-import { icons, type IconName } from '../../../icons/index.js';
-
-interface Props {
-  /** Shipped icon to render. Omit and pass a custom <svg> via the default slot. */
-  name?: IconName;
-  size?: 'sm' | 'md' | 'lg';
-  /** Continuous animation applied to the glyph (e.g. a loading spinner). */
-  animation?: 'spin';
-  label?: string;
-}
-
-const { name, size = 'md', animation, label, ...rest } = Astro.props;
-const hasSlot = Astro.slots.has('default');
-
-// slot wins over name; flag the redundant combination in development
-if (import.meta.env.DEV && name && hasSlot) {
-  console.warn(
-    '[pienter-ui] Icon received both a `name` and slot content; the slot is used and `name` is ignored.',
-  );
-}
-
-const svg = name ? icons[name] : '';
----
-
-{
-  hasSlot ? (
-    <span
-      class="pui-icon"
-      data-size={size}
-      data-animation={animation}
-      aria-hidden={!label}
-      aria-label={label}
-      role={label ? 'img' : undefined}
-      {...rest}
-    >
-      <slot />
-    </span>
-  ) : (
-    <span
-      class="pui-icon"
-      data-size={size}
-      data-animation={animation}
-      aria-hidden={!label}
-      aria-label={label}
-      role={label ? 'img' : undefined}
-      {...rest}
-      set:html={svg}
-    />
-  )
-}

package/components/feedback/alert/Alert.astro

@@ -1,52 +0,0 @@
----
-import './alert.css';
-import Icon from '../../display/icon/Icon.astro';
-import type { IconName } from '../../../icons/index.js';
-
-type Tone = 'brand' | 'success' | 'warning' | 'danger';
-
-interface Props {
-  tone?: Tone;
-  title?: string;
-  /** Override the tone's default icon with a shipped one. Use the `icon` slot for a custom <svg>. */
-  icon?: IconName;
-}
-
-const toneIconMap: Record<Tone, IconName> = {
-  brand: 'info',
-  success: 'circle-check',
-  warning: 'alert-triangle',
-  danger: 'circle-alert',
-};
-
-const { tone, title, icon, ...rest } = Astro.props;
-const resolvedIcon: IconName = icon ?? (tone ? toneIconMap[tone] : 'info');
-const hasIconSlot = Astro.slots.has('icon');
-
-// the icon slot wins over the `icon` name; flag the redundant combination in dev
-if (import.meta.env.DEV && icon && hasIconSlot) {
-  console.warn(
-    '[pienter-ui] Alert received both an `icon` name and an `icon` slot; the slot is used and `icon` is ignored.',
-  );
-}
----
-
-<div class="pui-alert" data-tone={tone} role="alert" {...rest}>
-  <span class="pui-alert__icon">
-    {
-      hasIconSlot ? (
-        <Icon size="md">
-          <slot name="icon" />
-        </Icon>
-      ) : (
-        <Icon name={resolvedIcon} size="md" />
-      )
-    }
-  </span>
-  <div class="pui-alert__content">
-    {title && <p class="pui-alert__title">{title}</p>}
-    <div class="pui-alert__body">
-      <slot />
-    </div>
-  </div>
-</div>

package/components/feedback/progress/Progress.astro

@@ -1,68 +0,0 @@
----
-import './progress.css';
-
-interface Props {
-  /**
-   * Current value of the progress bar. When `null` or `undefined`, the
-   * component renders the indeterminate ("loading") state per WAI-ARIA
-   * convention — `aria-valuenow` is OMITTED from the wrapper so assistive
-   * technology announces an indeterminate progressbar.
-   */
-  value?: number | null;
-  /** Maximum value of the range. */
-  max?: number;
-  /** Minimum value of the range. */
-  min?: number;
-  /**
-   * Accessible name for the progressbar — emitted as `aria-label`. Omit
-   * when an external `aria-labelledby` is supplied via `...rest`.
-   */
-  label?: string;
-  /** Tone variant — drives indicator color via `data-tone`. */
-  tone?: 'brand' | 'success' | 'warning' | 'danger';
-}
-
-const {
-  value = null,
-  max = 100,
-  min = 0,
-  label,
-  tone = 'brand',
-  ...rest
-} = Astro.props;
-
-const isIndeterminate = value === null || value === undefined;
-
-const clampedValue = isIndeterminate
-  ? min
-  : Math.min(Math.max(value as number, min), max);
-
-const span = max - min;
-const percent =
-  isIndeterminate || span <= 0 ? 0 : ((clampedValue - min) / span) * 100;
-
-const state: 'loading' | 'in-progress' | 'complete' = isIndeterminate
-  ? 'loading'
-  : clampedValue === max
-    ? 'complete'
-    : 'in-progress';
-
-const indicatorStyle: Record<string, string> = {};
-if (!isIndeterminate) {
-  indicatorStyle.width = `${percent}%`;
-}
----
-
-<div
-  class="pui-progress"
-  role="progressbar"
-  aria-valuenow={isIndeterminate ? undefined : clampedValue}
-  aria-valuemin={min}
-  aria-valuemax={max}
-  aria-label={label}
-  data-state={state}
-  data-tone={tone}
-  {...rest}
->
-  <div class="pui-progress__indicator" style={indicatorStyle}></div>
-</div>

package/components/feedback/skeleton/Skeleton.astro

@@ -1,32 +0,0 @@
----
-import './skeleton.css';
-
-interface Props {
-  variant?: 'text' | 'rect' | 'circle';
-  width?: string;
-  height?: string;
-  rounded?: boolean;
-}
-
-const {
-  variant = 'rect',
-  width,
-  height,
-  rounded = false,
-  ...rest
-} = Astro.props;
-
-const inlineStyle: Record<string, string> = {};
-if (width) inlineStyle.width = width;
-if (height) inlineStyle.height = height;
----
-
-<div
-  class="pui-skeleton"
-  data-variant={variant}
-  data-rounded={rounded ? '' : undefined}
-  style={inlineStyle}
-  aria-hidden="true"
-  {...rest}
->
-</div>

package/components/feedback/spinner/Spinner.astro

@@ -1,25 +0,0 @@
----
-// Spinner (Astro) — same contract as Spinner.vue; composes Icon so the spin stays in icon.css.
-import './spinner.css';
-import Icon from '../../display/icon/Icon.astro';
-
-interface Props {
-  size?: 'sm' | 'md' | 'lg' | 'xl';
-  /** Accessible name; supply it when the spinner is the only signal. See Spinner.vue. */
-  label?: string;
-}
-
-const { size = 'md', label, ...rest } = Astro.props;
----
-
-<span
-  class="pui-spinner"
-  data-size={size}
-  role={label ? 'status' : undefined}
-  aria-hidden={label ? undefined : 'true'}
-  {...rest}
->
-  <Icon name="loader" animation="spin" />
-  {/* Real text, not an aria-label — see Spinner.vue. */}
-  {label && <span class="pui-spinner__label">{label}</span>}
-</span>

package/components/feedback/toast/Toast.astro

@@ -1,50 +0,0 @@
----
-import './toast.css';
-import Icon from '../../display/icon/Icon.astro';
-import type { IconName } from '../../../icons/index.js';
-
-type Tone = 'brand' | 'success' | 'warning' | 'danger';
-
-interface Props {
-  tone?: Tone;
-  title: string;
-  message?: string;
-  dismissible?: boolean;
-  icon?: IconName;
-  action?: { label: string };
-}
-
-const toneIconMap: Record<Tone, IconName> = {
-  brand: 'info',
-  success: 'circle-check',
-  warning: 'alert-triangle',
-  danger: 'circle-alert',
-};
-
-const { tone, title, message, dismissible = true, icon, action } = Astro.props;
-const resolvedIcon: IconName = icon ?? (tone ? toneIconMap[tone] : 'info');
----
-
-<div class="pui-toast" data-tone={tone}>
-  <span class="pui-toast__icon" aria-hidden="true">
-    <Icon name={resolvedIcon} size="sm" />
-  </span>
-  <div class="pui-toast__body">
-    <p class="pui-toast__title">{title}</p>
-    {message && <p class="pui-toast__msg">{message}</p>}
-  </div>
-  {
-    action && (
-      <button class="pui-toast__action" type="button">
-        {action.label}
-      </button>
-    )
-  }
-  {
-    dismissible && (
-      <button class="pui-toast__close" type="button" aria-label="Close">
-        <Icon name="x" size="sm" />
-      </button>
-    )
-  }
-</div>