@portnet/ui 5.0.32 → 6.0.1

package/dist/v2/patterns/ActionBar.d.ts

@@ -0,0 +1,137 @@
+import * as React from "react";
+import type { ButtonProps } from "../components/Button";
+/**
+ * ActionBar - Portnet UI v2 (pattern)
+ *
+ * Charter §07 — render order (left → right):
+ *
+ *   [ghost/secondary…]  [primary]  […overflow]
+ *
+ * Slot-based variant resolution:
+ *   slot="primary"   → Button variant="primary"
+ *   slot="secondary" → Button variant={action.variant || "secondary"}
+ *   slot="overflow"  → Button variant={action.variant || "ghost"}
+ *
+ * maxVisible (default 2):
+ *   orderedAll = [primary, ...secondary, ...overflow]
+ *   first maxVisible → visible buttons / rest → "…"
+ *
+ * Breadcrumb collapse (R-RS.5):
+ *   Below the `sm` breakpoint TOKEN (< 481px) a long trail used to
+ *   flex-wrap onto several lines, pushing the page title down. When the
+ *   trail has more than `collapseAfter` crumbs (default 3) the middle is
+ *   collapsed to a single "…" toggle that shows [first] › … › [last];
+ *   pressing it expands the full trail in place. Desktop always renders
+ *   the full trail. Keeps the nav to one line on phones (WCAG 1.4.10
+ *   Reflow) without hiding navigation from AT — the toggle is a real
+ *   button with an accessible name.
+ *
+ * ── `surface` DEFAULTS TO false — A PAGE HEADER IS NOT A CARD ────────
+ *
+ * The platform rule is that a page header sits on the page background, never
+ * on a white card. This default used to be `true`, which meant every call site
+ * that did not opt out rendered a --surface card with a bottom border — making
+ * the exception the norm across the GU modules.
+ *
+ * Note that `surface` drives TWO things, because `useAccent` is derived from
+ * it: the background/border AND the colour of the title, icon, back-arrow and
+ * crumb trail (--accent when non-surface, --fg / --fg-subtle when surfaced).
+ * They are deliberately coupled — an accent title on a white card reads as a
+ * link, and a near-black title on the page background loses the visual anchor
+ * the header needs. Decoupling them would need a separate prop and a design
+ * decision, not a default change.
+ *
+ * Pass surface={true} to opt back in to the card treatment where a header is
+ * genuinely nested inside a panel rather than heading a page.
+ *
+ * ── Subtitle visibility (S-01) ───────────────────────────────────────
+ *
+ * The subtitle renders at EVERY breakpoint. It used to be hidden below the `sm`
+ * token via `display: none`, which made every consuming module fail the
+ * mandatory "Never omit subtitles" pattern on phones — and removed the text from
+ * the accessibility tree, not just from the layout. On `xs` it is now bounded to
+ * two lines with a line-clamp instead; `sm` and above are unchanged. See the
+ * inline note at the render site for the full rationale.
+ */
+/** Variant union, derived from Button (single source of truth). */
+type ActionVariant = NonNullable<ButtonProps["variant"]>;
+/** Structured breadcrumb entry (as opposed to a plain renderable node). */
+export interface BreadcrumbItem {
+    label?: React.ReactNode | undefined;
+    icon?: React.ReactNode | undefined;
+    onClick?: (() => void) | undefined;
+    href?: string | undefined;
+    ariaLabel?: string | undefined;
+}
+/** A breadcrumb entry is either a plain node or a structured item. */
+export type CrumbEntry = React.ReactNode | BreadcrumbItem;
+/** Action descriptor for primary / secondary / overflow slots. */
+export interface ActionBarAction {
+    label?: React.ReactNode | undefined;
+    icon?: React.ReactNode | undefined;
+    iconRight?: React.ReactNode | undefined;
+    onClick?: (() => void) | undefined;
+    disabled?: boolean | undefined;
+    loading?: boolean | undefined;
+    variant?: ActionVariant | undefined;
+    /** Overflow-only (surfaced when the action falls into the OverflowMenu). */
+    shortcut?: React.ReactNode | undefined;
+    danger?: boolean | undefined;
+    divider?: boolean | undefined;
+    /**
+     * ARIA attributes, forwarded verbatim to the rendered `<Button>`.
+     *
+     * `renderButton` destructures the known fields above and spreads the
+     * REMAINDER onto the Button (`{...rest}`), so any `aria-*` key a host supplies
+     * already reaches the DOM at runtime. This pattern index signature declares
+     * that contract, which was previously implemented but undeclared — forcing
+     * strict-mode consumers to either drop the attribute (losing the behaviour) or
+     * assert their way past the type.
+     *
+     * Primary use case: `aria-keyshortcuts` on a page's create CTA, so screen
+     * reader users discover a keyboard shortcut on focus (WCAG 2.1.4).
+     */
+    [ariaAttribute: `aria-${string}`]: string | undefined;
+}
+export interface ActionBarLabels {
+    back?: string | undefined;
+    breadcrumb?: string | undefined;
+    home?: string | undefined;
+    expandCrumbs?: string | undefined;
+}
+export interface ActionBarProps {
+    /** Home crumb: a callback (onClick) or an href string. */
+    home?: string | (() => void) | undefined;
+    /** Back-arrow callback (top-bar). */
+    back?: (() => void) | undefined;
+    breadcrumb?: CrumbEntry[] | undefined;
+    title: React.ReactNode;
+    subtitle?: React.ReactNode | undefined;
+    icon?: React.ReactNode | undefined;
+    primary?: ActionBarAction | undefined;
+    secondary?: ActionBarAction[] | undefined;
+    overflow?: ActionBarAction[] | undefined;
+    /** Number of actions shown before the rest collapse into the menu. @default 2 */
+    maxVisible?: number | undefined;
+    meta?: React.ReactNode | undefined;
+    sticky?: boolean | undefined;
+    /**
+     * Render the header as a raised white card instead of on the page
+     * background.
+     *
+     * @default false — a page header sits on the background (platform rule).
+     *
+     * Also governs text colour: when false, the title, icon, back-arrow and
+     * crumbs render in --accent; when true they render in --fg / --fg-subtle.
+     * See the note in the module docstring for why the two are coupled.
+     *
+     * Pass true only where the header genuinely heads a panel rather than a page.
+     */
+    surface?: boolean | undefined;
+    /** Collapse the breadcrumb middle on mobile past this many crumbs. @default 3 */
+    collapseAfter?: number | undefined;
+    labels?: ActionBarLabels | undefined;
+}
+declare function ActionBar({ home, back, breadcrumb, title, subtitle, icon, primary, secondary, overflow, maxVisible, meta, sticky, surface, collapseAfter, labels, }: ActionBarProps): React.JSX.Element;
+export default ActionBar;
+//# sourceMappingURL=ActionBar.d.ts.map

package/dist/v2/patterns/ActionBar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ActionBar.d.ts","sourceRoot":"","sources":["../../../src/lib/v2/patterns/ActionBar.tsx"],"names":[],"mappings":"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"}