@pienter/ui 0.3.0 → 0.7.1

package/utils/cms/index.ts

@@ -0,0 +1,283 @@
+import { formatSort, parseSort, type SortState } from '../sort/index.js';
+
+export type JsonValue =
+    string | number | boolean | null | JsonObject | JsonValue[];
+export interface JsonObject {
+    [key: string]: JsonValue;
+}
+export type ValuePath = readonly (string | number)[];
+export interface ValidationIssue {
+    path: ValuePath;
+    messages: string[];
+}
+export interface ApiError {
+    code: string;
+    message: string;
+    issues?: ValidationIssue[];
+}
+export interface ErrorResponse {
+    error: ApiError;
+}
+export interface ItemResponse<T> {
+    data: T;
+}
+export interface ListResponse<T> {
+    data: T[];
+    meta: { page: number; page_size: number; total: number };
+}
+export type ListLoader<T> = (
+    query: ListQuery,
+    context: { signal: AbortSignal },
+) => Promise<ListResponse<T>>;
+export interface ListQuery {
+    page: number;
+    page_size: number;
+    search: string;
+    sort: SortState;
+    filters: Record<string, string>;
+}
+export interface QueryOptions {
+    sorts: readonly string[];
+    filters: readonly string[];
+    defaultPageSize?: number;
+    maxPageSize?: number;
+}
+
+export class QueryError extends Error {
+    readonly code = 'invalid_query';
+    constructor(message: string) {
+        super(message);
+        this.name = 'QueryError';
+    }
+}
+
+function pageSizes(options: QueryOptions) {
+    const max = options.maxPageSize ?? 100;
+    const size = options.defaultPageSize ?? 20;
+    if (
+        !Number.isInteger(max) ||
+        max < 1 ||
+        max > 100 ||
+        !Number.isInteger(size) ||
+        size < 1 ||
+        size > max
+    ) {
+        throw new QueryError(
+            'Page size defaults must fit the supported range 1–100.',
+        );
+    }
+    return { max, size };
+}
+
+function integer(
+    value: number,
+    name: string,
+    max = Number.MAX_SAFE_INTEGER,
+): number {
+    if (!Number.isSafeInteger(value) || value < 1 || value > max) {
+        throw new QueryError(
+            `${name} must be an integer between 1 and ${max}.`,
+        );
+    }
+    return value;
+}
+
+function filterName(name: string): boolean {
+    return (
+        /^[a-zA-Z0-9_]+$/.test(name) &&
+        !['__proto__', 'prototype', 'constructor'].includes(name)
+    );
+}
+
+export function normalizeListQuery(
+    query: ListQuery,
+    options: QueryOptions,
+): ListQuery {
+    const { max } = pageSizes(options);
+    const page = integer(query.page, 'page');
+    const page_size = integer(query.page_size, 'page_size', max);
+    if (typeof query.search !== 'string')
+        throw new QueryError('Expected a search string.');
+    const sort = query.sort;
+    if (
+        sort !== null &&
+        (typeof sort !== 'object' ||
+            typeof sort.key !== 'string' ||
+            !sort.key ||
+            sort.key.startsWith('-') ||
+            !['asc', 'desc'].includes(sort.direction))
+    )
+        throw new QueryError(
+            'Expected a sort field and asc or desc direction.',
+        );
+    if (sort && !options.sorts.includes(sort.key))
+        throw new QueryError('Unsupported sort field.');
+    if (
+        !query.filters ||
+        typeof query.filters !== 'object' ||
+        Array.isArray(query.filters)
+    )
+        throw new QueryError('Expected a filter map.');
+    const filters: Record<string, string> = {};
+    for (const key of Object.keys(query.filters).sort()) {
+        if (!filterName(key) || !options.filters.includes(key))
+            throw new QueryError(
+                `Unsupported filter parameter: filter[${key}].`,
+            );
+        const value = query.filters[key];
+        if (typeof value !== 'string')
+            throw new QueryError(`Expected a string filter value: ${key}.`);
+        filters[key] = value;
+    }
+    return {
+        page,
+        page_size,
+        search: query.search,
+        sort: sort ? { key: sort.key, direction: sort.direction } : null,
+        filters,
+    };
+}
+
+export function decodeListQuery(
+    params: URLSearchParams,
+    options: QueryOptions,
+): ListQuery {
+    const { max, size } = pageSizes(options);
+    for (const key of ['page', 'page_size', 'search', 'sort']) {
+        if (params.getAll(key).length > 1)
+            throw new QueryError(`Duplicate ${key} parameter.`);
+    }
+    const rawSort = params.get('sort') ?? '';
+    const sort = rawSort ? parseSort(rawSort) : null;
+    if (rawSort && (!sort || sort.key.startsWith('-')))
+        throw new QueryError('Unsupported sort field.');
+    const filters: Record<string, string> = {};
+    for (const [key, value] of params) {
+        if (
+            ['page', 'page_size', 'search', 'sort'].some((name) =>
+                key.startsWith(`${name}[`),
+            )
+        )
+            throw new QueryError(`Expected a scalar parameter: ${key}.`);
+        if (key !== 'filter' && !key.startsWith('filter[')) continue;
+        const match = /^filter\[([a-zA-Z0-9_]+)\]$/.exec(key);
+        const name = match?.[1];
+        if (!name || !filterName(name))
+            throw new QueryError(`Unsupported filter parameter: ${key}.`);
+        if (params.getAll(key).length !== 1)
+            throw new QueryError(`Duplicate filter: ${name}.`);
+        filters[name] = value;
+    }
+    function number(name: string, fallback: number, max: number): number {
+        const value = params.get(name);
+        if (value === null) return fallback;
+        if (!/^[1-9]\d*$/.test(value))
+            throw new QueryError(
+                `${name} must be an integer between 1 and ${max}.`,
+            );
+        return Number(value);
+    }
+    return normalizeListQuery(
+        {
+            page: number('page', 1, Number.MAX_SAFE_INTEGER),
+            page_size: number('page_size', size, max),
+            search: params.get('search') ?? '',
+            sort,
+            filters,
+        },
+        options,
+    );
+}
+
+export function encodeListQuery(query: ListQuery): URLSearchParams {
+    const normalized = normalizeListQuery(query, {
+        sorts: query.sort ? [query.sort.key] : [],
+        filters: query.filters ? Object.keys(query.filters) : [],
+    });
+    const params = new URLSearchParams({
+        page: String(normalized.page),
+        page_size: String(normalized.page_size),
+    });
+    if (normalized.search) params.set('search', normalized.search);
+    if (normalized.sort) params.set('sort', formatSort(normalized.sort)!);
+    for (const [key, value] of Object.entries(normalized.filters))
+        params.set(`filter[${key}]`, value);
+    return params;
+}
+
+export function cloneRecord<T>(record: T): T {
+    return JSON.parse(JSON.stringify(record)) as T;
+}
+
+export function readPath(record: unknown, path: ValuePath): unknown {
+    let value = record;
+    for (const key of path) {
+        if (
+            value === null ||
+            typeof value !== 'object' ||
+            ['__proto__', 'prototype', 'constructor'].includes(String(key))
+        )
+            return undefined;
+        if (
+            Array.isArray(value) !== (typeof key === 'number') ||
+            !Object.hasOwn(value, key)
+        )
+            return undefined;
+        value = (value as Record<string | number, unknown>)[key];
+    }
+    return value;
+}
+
+export function updatePath<T extends object>(
+    record: T,
+    path: ValuePath,
+    value: unknown,
+): T {
+    if (
+        !path.length ||
+        typeof path[0] !== 'string' ||
+        path.some((key) =>
+            typeof key === 'number'
+                ? !Number.isInteger(key) || key < 0 || key > 4294967294
+                : !key ||
+                  ['__proto__', 'prototype', 'constructor'].includes(key),
+        )
+    ) {
+        throw new TypeError(
+            'Expected a non-empty path of safe object keys and array indices.',
+        );
+    }
+    const copy = cloneRecord(record);
+    let target = copy as Record<string | number, unknown>;
+    for (let i = 0; i < path.length; i++) {
+        const key = path[i]!;
+        if (Array.isArray(target) !== (typeof key === 'number'))
+            throw new TypeError(
+                'Path does not match its object or array container.',
+            );
+        if (Array.isArray(target) && Number(key) > target.length)
+            throw new TypeError('Array paths cannot create sparse records.');
+        if (i === path.length - 1) {
+            target[key] = value === undefined ? undefined : cloneRecord(value);
+            break;
+        }
+        const next = target[key];
+        if (next === null || typeof next !== 'object')
+            target[key] = typeof path[i + 1] === 'number' ? [] : {};
+        target = target[key] as Record<string | number, unknown>;
+    }
+    return copy;
+}
+
+export function errorsFor(
+    issues: readonly ValidationIssue[],
+    path: ValuePath,
+): string[] {
+    return issues
+        .filter(
+            (issue) =>
+                issue.path.length === path.length &&
+                issue.path.every((part, index) => part === path[index]),
+        )
+        .flatMap((issue) => issue.messages);
+}

package/utils/cms/schema.json

@@ -0,0 +1,126 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:pienter:cms:backend:v1",
+  "title": "Pienter CMS backend contract v1",
+  "description": "Common response envelopes and normalized list query. Validate domain records and endpoint-specific sort/filter rules separately.",
+  "oneOf": [
+    { "$ref": "#/$defs/ListResponse" },
+    { "$ref": "#/$defs/ItemResponse" },
+    { "$ref": "#/$defs/ErrorResponse" },
+    { "$ref": "#/$defs/ListQuery" }
+  ],
+  "$defs": {
+    "Record": {
+      "type": "object",
+      "description": "A domain record whose properties are defined by the endpoint.",
+      "additionalProperties": true
+    },
+    "ListResponse": {
+      "type": "object",
+      "required": ["data", "meta"],
+      "additionalProperties": false,
+      "properties": {
+        "data": { "type": "array", "items": { "$ref": "#/$defs/Record" } },
+        "meta": {
+          "type": "object",
+          "required": ["page", "page_size", "total"],
+          "additionalProperties": false,
+          "properties": {
+            "page": { "$ref": "#/$defs/Page" },
+            "page_size": { "$ref": "#/$defs/PageSize" },
+            "total": {
+              "type": "integer",
+              "minimum": 0,
+              "maximum": 9007199254740991
+            }
+          }
+        }
+      }
+    },
+    "ItemResponse": {
+      "type": "object",
+      "required": ["data"],
+      "additionalProperties": false,
+      "properties": { "data": { "$ref": "#/$defs/Record" } }
+    },
+    "ErrorResponse": {
+      "type": "object",
+      "required": ["error"],
+      "additionalProperties": false,
+      "properties": {
+        "error": {
+          "type": "object",
+          "required": ["code", "message"],
+          "additionalProperties": false,
+          "properties": {
+            "code": { "type": "string", "minLength": 1 },
+            "message": { "type": "string", "minLength": 1 },
+            "issues": {
+              "type": "array",
+              "items": { "$ref": "#/$defs/ValidationIssue" }
+            }
+          }
+        }
+      }
+    },
+    "ValidationIssue": {
+      "type": "object",
+      "required": ["path", "messages"],
+      "additionalProperties": false,
+      "properties": {
+        "path": {
+          "type": "array",
+          "description": "Object keys and zero-based array positions in the submitted value; an empty array addresses the whole value.",
+          "items": {
+            "oneOf": [
+              { "type": "string", "minLength": 1 },
+              { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }
+            ]
+          }
+        },
+        "messages": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+    "ListQuery": {
+      "type": "object",
+      "description": "Normalized output from decoding URL query parameters, after defaults are applied. This is not a JSON request body.",
+      "required": ["page", "page_size", "search", "sort", "filters"],
+      "additionalProperties": false,
+      "properties": {
+        "page": { "$ref": "#/$defs/Page", "default": 1 },
+        "page_size": { "$ref": "#/$defs/PageSize", "default": 20 },
+        "search": { "type": "string", "default": "" },
+        "sort": {
+          "default": null,
+          "oneOf": [
+            { "type": "null" },
+            {
+              "type": "object",
+              "required": ["key", "direction"],
+              "additionalProperties": false,
+              "properties": {
+                "key": { "type": "string", "minLength": 1 },
+                "direction": { "enum": ["asc", "desc"] }
+              }
+            }
+          ]
+        },
+        "filters": {
+          "type": "object",
+          "default": {},
+          "propertyNames": {
+            "pattern": "^[a-zA-Z0-9_]+$",
+            "not": { "enum": ["__proto__", "prototype", "constructor"] }
+          },
+          "additionalProperties": { "type": "string" }
+        }
+      }
+    },
+    "Page": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 },
+    "PageSize": { "type": "integer", "minimum": 1, "maximum": 100 }
+  }
+}

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>