@fairfox/polly 0.23.0 → 0.25.0

package/dist/src/polly-ui/ConfirmDialog.d.ts

@@ -0,0 +1,24 @@
+/**
+ * ConfirmDialog — Promise-returning confirmation primitive.
+ *
+ * `confirm({ title, body, danger })` returns Promise<boolean>. Opens the
+ * rendered `<ConfirmDialog.Host />` modal (which must be mounted once at
+ * the app root). User picking confirm or cancel resolves the promise.
+ * Escape, backdrop click, and explicit `.dismiss()` resolve false.
+ */
+import type { JSX } from "preact";
+export type ConfirmOptions = {
+    title: string;
+    body?: string;
+    danger?: boolean;
+    confirmLabel?: string;
+    cancelLabel?: string;
+};
+export declare function confirm(options: ConfirmOptions): Promise<boolean>;
+/** Renders the active confirm dialog. Mount once near the app root. */
+declare function Host(): JSX.Element | null;
+export declare const ConfirmDialog: {
+    Host: typeof Host;
+    confirm: typeof confirm;
+};
+export {};

package/dist/src/polly-ui/Layout.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Layout — the one primitive that owns layouting concerns.
+ *
+ * Every other component in @fairfox/polly/ui (and every consumer app
+ * that runs `polly quality css-layout`) routes flex/grid decisions
+ * through this component. Props map to CSS custom properties so the
+ * stylesheet can read them uniformly and so consumers can override
+ * any of them in media queries without touching specificity.
+ */
+import { type ComponentChildren, type JSX } from "preact";
+export type LayoutProps = {
+    children: ComponentChildren;
+    /** Polymorphic element (div, section, header, nav, …). Defaults to 'div'. */
+    as?: keyof JSX.IntrinsicElements;
+    /** CSS grid structure. */
+    rows?: string;
+    columns?: string;
+    autoFlow?: string;
+    autoRows?: string;
+    autoColumns?: string;
+    /** display: contents — lets children participate in an ancestor grid. */
+    contents?: boolean;
+    /** Inherit parent grid tracks via CSS subgrid. */
+    subgrid?: boolean;
+    /** Spacing. */
+    gap?: string;
+    padding?: string;
+    /** Sizing. */
+    height?: string;
+    minHeight?: string;
+    /** Container alignment. */
+    justifyItems?: string;
+    alignItems?: string;
+    justifyContent?: string;
+    alignContent?: string;
+    /** Self alignment (when this Layout is an item in a parent grid). */
+    justifySelf?: string;
+    alignSelf?: string;
+    /** Collapse to a single column at ≤640px. */
+    stackOnMobile?: boolean;
+    className?: string;
+    onClick?: JSX.MouseEventHandler<HTMLElement>;
+    onKeyDown?: JSX.KeyboardEventHandler<HTMLElement>;
+    role?: JSX.AriaRole;
+    tabIndex?: number;
+    id?: string;
+    "aria-label"?: string;
+    "aria-labelledby"?: string;
+    "aria-describedby"?: string;
+};
+export declare function Layout(props: LayoutProps): JSX.Element;

package/dist/src/polly-ui/Modal.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Modal — compound dialog with focus trap, Escape handling, portal,
+ * and overlay-stack integration.
+ *
+ * Root takes a `when` signal (or boolean). When truthy the content mounts
+ * into the OverlayRoot portal, focus moves inside, Tab is trapped, Escape
+ * fires `data-action="modal:close"` (or the overlay registry's onClose
+ * callback), and the body scroll locks.
+ */
+import type { ReadonlySignal } from "@preact/signals";
+import { type ComponentChildren } from "preact";
+type RootProps = {
+    when: ReadonlySignal<boolean> | boolean;
+    onClose?: () => void;
+    children: ComponentChildren;
+    /** Accessible label source: "title" uses the <Modal.Title> id, or pass an explicit label. */
+    "aria-label"?: string;
+};
+declare function Root({ when, onClose, children, "aria-label": ariaLabel }: RootProps): import("preact").VNode<any> | null;
+declare function Backdrop(): import("preact").JSX.Element;
+declare function Content({ children }: {
+    children: ComponentChildren;
+}): import("preact").JSX.Element;
+declare function Header({ children }: {
+    children: ComponentChildren;
+}): import("preact").JSX.Element;
+declare function Title({ children }: {
+    children: ComponentChildren;
+}): import("preact").JSX.Element;
+declare function Body({ children }: {
+    children: ComponentChildren;
+}): import("preact").JSX.Element;
+declare function Footer({ children }: {
+    children: ComponentChildren;
+}): import("preact").JSX.Element;
+type CloseProps = {
+    children: ComponentChildren;
+    /** Fire a registered data-action instead of calling the onClose callback. */
+    action?: string;
+};
+declare function Close({ children, action }: CloseProps): import("preact").JSX.Element;
+export declare const Modal: {
+    Root: typeof Root;
+    Backdrop: typeof Backdrop;
+    Content: typeof Content;
+    Header: typeof Header;
+    Title: typeof Title;
+    Body: typeof Body;
+    Footer: typeof Footer;
+    Close: typeof Close;
+};
+export {};

package/dist/src/polly-ui/OverlayRoot.d.ts

@@ -0,0 +1,10 @@
+/**
+ * OverlayRoot — portal target for stacked overlays.
+ *
+ * Apps render <OverlayRoot /> once, typically as the last child of the
+ * app root. Modal, ConfirmDialog, and Toast portal into this element;
+ * the scroll lock toggles based on the overlay registry count.
+ */
+export declare function OverlayRoot(): import("preact").JSX.Element;
+/** Get the mount node for portaled overlays. Returns null before mount. */
+export declare function getOverlayRootNode(): HTMLElement | null;

package/dist/src/polly-ui/TextInput.d.ts

@@ -0,0 +1,31 @@
+/**
+ * TextInput — passive, signal-friendly native input wrapper.
+ *
+ * Designed to live inside <ActionForm>. Pass a plain string for
+ * uncontrolled mode (FormData-on-submit picks up the value) or a
+ * Signal<string> for controlled mode. Either way, a11y attributes are
+ * wired by the shared input-base, the stable `[data-polly-input]` hook
+ * is applied for styling, and `invalid` flips `aria-invalid` and
+ * `data-state="invalid"` for consumer selectors.
+ */
+import type { Signal } from "@preact/signals";
+import type { JSX } from "preact";
+type Variant = "single" | "multi";
+export type TextInputProps = {
+    name: string;
+    /** Signal<string> for controlled, string for uncontrolled default. */
+    value?: Signal<string> | string;
+    variant?: Variant;
+    placeholder?: string;
+    invalid?: boolean;
+    required?: boolean;
+    disabled?: boolean;
+    readOnly?: boolean;
+    id?: string;
+    describedBy?: string;
+    rows?: number;
+    autoFocus?: boolean;
+    className?: string;
+};
+export declare function TextInput(props: TextInputProps): JSX.Element;
+export {};

package/dist/src/polly-ui/Toast.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Toast — consumer-facing surface for the global errorState.
+ *
+ * Renders every entry of the `errorState` signal into a viewport mounted
+ * inside OverlayRoot. `aria-live` is polite for info/warning and
+ * assertive for error severity. Each item auto-dismisses after
+ * `autoDismissMs` unless the user hovers the viewport. Clicking a
+ * toast or its close button removes that single entry.
+ */
+import type { JSX } from "preact";
+export type ToastViewportProps = {
+    autoDismissMs?: number;
+    className?: string;
+};
+declare function Viewport(props: ToastViewportProps): JSX.Element | null;
+export declare const Toast: {
+    Viewport: typeof Viewport;
+};
+export {};

package/dist/src/polly-ui/index.css

@@ -0,0 +1,319 @@
+/* src/polly-ui/ActionForm.module.css */
+@layer polly-components {
+  .form_oqTahQ {
+    inline-size: 100%;
+  }
+
+  .form_oqTahQ[aria-busy="true"] {
+    opacity: var(--polly-opacity-disabled);
+    pointer-events: none;
+  }
+}
+
+/* src/polly-ui/ActionInput.module.css */
+@layer polly-components {
+  .root_-n6UrQ {
+    box-sizing: border-box;
+    padding: var(--polly-space-sm) var(--polly-space-md);
+    font: inherit;
+    font-family: var(--polly-font-sans);
+    color: var(--polly-text);
+    line-height: var(--polly-line-height-base);
+    border: var(--polly-border-width-default) solid transparent;
+    border-radius: var(--polly-radius-md);
+    min-block-size: calc(1.5em + 2 * var(--polly-space-sm)  + 2 * var(--polly-border-width-default));
+    inline-size: 100%;
+  }
+
+  .view_-n6UrQ {
+    cursor: text;
+    white-space: pre-wrap;
+    word-break: break-word;
+    transition: background var(--polly-motion-fast) ease, border-color var(--polly-motion-fast) ease;
+    background: none;
+  }
+
+  .view_-n6UrQ:hover {
+    background: var(--polly-surface-sunken);
+    border-color: var(--polly-border);
+  }
+
+  .edit_-n6UrQ {
+    background: var(--polly-surface);
+    border-color: var(--polly-border);
+  }
+
+  .placeholder_-n6UrQ {
+    color: var(--polly-text-muted);
+    font-style: italic;
+  }
+
+  .root_-n6UrQ[data-variant="multi"] {
+    field-sizing: content;
+    resize: vertical;
+    max-block-size: 40em;
+  }
+}
+
+/* src/polly-ui/ConfirmDialog.module.css */
+@layer polly-components {
+  .actions_ZfTX4A {
+    display: grid;
+    grid-auto-flow: column;
+    gap: var(--polly-space-sm);
+    justify-content: end;
+  }
+
+  .cancel_ZfTX4A, .confirm_ZfTX4A, .confirmDanger_ZfTX4A {
+    appearance: none;
+    padding: var(--polly-space-sm) var(--polly-space-lg);
+    font: inherit;
+    font-weight: var(--polly-weight-medium);
+    border: var(--polly-border-width-default) solid var(--polly-border);
+    border-radius: var(--polly-radius-md);
+    cursor: pointer;
+    transition: background var(--polly-motion-fast) ease;
+  }
+
+  .cancel_ZfTX4A {
+    background: var(--polly-surface);
+    color: var(--polly-text);
+  }
+
+  .cancel_ZfTX4A:hover {
+    background: var(--polly-surface-sunken);
+  }
+
+  .confirm_ZfTX4A {
+    background: var(--polly-accent);
+    color: var(--polly-accent-contrast);
+    border-color: var(--polly-accent);
+  }
+
+  .confirm_ZfTX4A:hover {
+    filter: brightness(1.05);
+  }
+
+  .confirmDanger_ZfTX4A {
+    background: var(--polly-danger);
+    color: var(--polly-danger-contrast);
+    border-color: var(--polly-danger);
+  }
+
+  .confirmDanger_ZfTX4A:hover {
+    filter: brightness(1.05);
+  }
+}
+
+/* src/polly-ui/Modal.module.css */
+@layer polly-components {
+  .container_fLMrWA {
+    position: fixed;
+    display: grid;
+    pointer-events: none;
+    place-items:  center;
+    inset: 0;
+  }
+
+  .backdrop_fLMrWA {
+    position: absolute;
+    background: color-mix(in srgb, var(--polly-text) 50%, transparent);
+    pointer-events: auto;
+    inset: 0;
+  }
+
+  .surface_fLMrWA {
+    position: relative;
+    pointer-events: auto;
+    background: var(--polly-surface-raised);
+    color: var(--polly-text);
+    border: var(--polly-border-width-default) solid var(--polly-border);
+    border-radius: var(--polly-radius-lg);
+    box-shadow: var(--polly-shadow-lg);
+    max-inline-size: min(640px, calc(100vw - 2 * var(--polly-space-lg)));
+    max-block-size: calc(100vh - 2 * var(--polly-space-lg));
+    overflow: auto;
+  }
+
+  .header_fLMrWA {
+    padding: var(--polly-space-lg);
+    border-block-end: var(--polly-border-width-default) solid var(--polly-border);
+  }
+
+  .title_fLMrWA {
+    font-size: var(--polly-text-xl);
+    font-weight: var(--polly-weight-bold);
+    line-height: var(--polly-line-height-tight);
+    margin: 0;
+  }
+
+  .body_fLMrWA {
+    padding: var(--polly-space-lg);
+  }
+
+  .footer_fLMrWA {
+    padding: var(--polly-space-lg);
+    border-block-start: var(--polly-border-width-default) solid var(--polly-border);
+  }
+
+  .close_fLMrWA {
+    appearance: none;
+    color: var(--polly-text);
+    border: var(--polly-border-width-default) solid transparent;
+    border-radius: var(--polly-radius-md);
+    padding: var(--polly-space-sm) var(--polly-space-md);
+    font: inherit;
+    cursor: pointer;
+    transition: background var(--polly-motion-fast) ease, border-color var(--polly-motion-fast) ease;
+    background: none;
+  }
+
+  .close_fLMrWA:hover {
+    background: var(--polly-surface-sunken);
+    border-color: var(--polly-border);
+  }
+}
+
+/* src/polly-ui/OverlayRoot.module.css */
+@layer polly-components {
+  .root_CqRu1Q {
+    position: fixed;
+    pointer-events: none;
+    inset: 0;
+  }
+}
+
+/* src/polly-ui/Layout.module.css */
+@layer polly-components {
+  .layout_QgwWPg {
+    --l-cols: none;
+    --l-rows: none;
+    --l-gap: 0;
+    --l-p: 0;
+    --l-h: auto;
+    --l-mh: auto;
+    --l-ji: stretch;
+    --l-ai: start;
+    --l-jc: normal;
+    --l-ac: normal;
+    --l-js: auto;
+    --l-as: auto;
+    --l-flow: row;
+    --l-arows: auto;
+    --l-acols: auto;
+    --l-col: auto;
+    display: grid;
+    grid-template-columns: var(--l-cols);
+    grid-template-rows: var(--l-rows);
+    gap: var(--l-gap);
+    padding: var(--l-p);
+    height: var(--l-h);
+    min-height: var(--l-mh);
+    justify-items: var(--l-ji);
+    align-items: var(--l-ai);
+    justify-content: var(--l-jc);
+    align-content: var(--l-ac);
+    justify-self: var(--l-js);
+    align-self: var(--l-as);
+    grid-auto-flow: var(--l-flow);
+    grid-auto-rows: var(--l-arows);
+    grid-auto-columns: var(--l-acols);
+    grid-column: var(--l-col);
+    inline-size: 100%;
+  }
+
+  @media (max-width: 640px) {
+    .stackOnMobile_QgwWPg {
+      grid-template-columns: 1fr;
+      grid-auto-flow: row;
+      grid-column: auto;
+    }
+  }
+}
+
+/* src/polly-ui/TextInput.module.css */
+@layer polly-components {
+  .input_ez4_Vg {
+    box-sizing: border-box;
+    padding: var(--polly-space-sm) var(--polly-space-md);
+    font: inherit;
+    font-family: var(--polly-font-sans);
+    color: var(--polly-text);
+    background: var(--polly-surface);
+    border: var(--polly-border-width-default) solid var(--polly-border);
+    border-radius: var(--polly-radius-md);
+    transition: border-color var(--polly-motion-fast) ease, background var(--polly-motion-fast) ease;
+    inline-size: 100%;
+  }
+
+  .input_ez4_Vg:hover {
+    border-color: var(--polly-border-strong);
+  }
+
+  .input_ez4_Vg[data-state="invalid"] {
+    border-color: var(--polly-danger);
+  }
+
+  .input_ez4_Vg:disabled {
+    opacity: var(--polly-opacity-disabled);
+    cursor: not-allowed;
+  }
+
+  .input_ez4_Vg[data-polly-input-variant="multi"] {
+    field-sizing: content;
+    min-block-size: calc(1.5em + 2 * var(--polly-space-sm)  + 2 * var(--polly-border-width-default));
+    resize: vertical;
+    max-block-size: 40em;
+  }
+}
+
+/* src/polly-ui/Toast.module.css */
+@layer polly-components {
+  .viewport_xVzRuA {
+    display: grid;
+    gap: var(--polly-space-sm);
+  }
+
+  .item_xVzRuA {
+    display: grid;
+    grid-template-columns: 1fr auto;
+    gap: var(--polly-space-md);
+    padding: var(--polly-space-md) var(--polly-space-lg);
+    background: var(--polly-surface-raised);
+    color: var(--polly-text);
+    border: var(--polly-border-width-default) solid var(--polly-border);
+    border-radius: var(--polly-radius-md);
+    box-shadow: var(--polly-shadow-md);
+    align-items:  center;
+    min-inline-size: 16em;
+    max-inline-size: 28em;
+  }
+
+  .item_xVzRuA[data-severity="error"] {
+    border-color: var(--polly-danger);
+  }
+
+  .item_xVzRuA[data-severity="warning"] {
+    border-color: var(--polly-warning);
+  }
+
+  .message_xVzRuA {
+    font-size: var(--polly-text-md);
+    line-height: var(--polly-line-height-base);
+  }
+
+  .close_xVzRuA {
+    appearance: none;
+    color: inherit;
+    border: var(--polly-border-width-default) solid transparent;
+    border-radius: var(--polly-radius-sm);
+    padding: var(--polly-space-xs) var(--polly-space-sm);
+    font: inherit;
+    cursor: pointer;
+    background: none;
+  }
+
+  .close_xVzRuA:hover {
+    background: var(--polly-surface-sunken);
+  }
+}

package/dist/src/polly-ui/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @fairfox/polly/ui — compound UI primitives.
+ *
+ * Every primitive is built on @fairfox/polly/actions: data-action hooks
+ * route events into the consumer's action registry, semantic tokens
+ * drive all visual values, and the <Layout> primitive owns every
+ * layouting concern. Ship styles.css and theme.css alongside to pick up
+ * the default look; redefine variables to re-theme.
+ */
+export { ActionForm, type ActionFormProps } from "./ActionForm.tsx";
+export { ActionInput, type ActionInputProps, type ActionInputSaveOn, type ActionInputVariant, } from "./ActionInput.tsx";
+export { ConfirmDialog, type ConfirmOptions, confirm } from "./ConfirmDialog.tsx";
+export { Layout, type LayoutProps } from "./Layout.tsx";
+export { Modal } from "./Modal.tsx";
+export { getOverlayRootNode, OverlayRoot } from "./OverlayRoot.tsx";
+export { TextInput, type TextInputProps } from "./TextInput.tsx";
+export { Toast, type ToastViewportProps } from "./Toast.tsx";