@photon-ai/pho-ui 0.7.2 → 1.0.1

package/dist/src/components/menu/menu-pending.d.ts

@@ -0,0 +1,43 @@
+import { ComponentType, MouseEvent as ReactMouseEvent, ReactNode, RefObject } from 'react';
+/** Imperative actions exposed by Base UI menu `actionsRef`. */
+interface RootActions {
+    unmount: () => void;
+    close: () => void;
+}
+/**
+ * Whether the surrounding menu has an async item promise in flight —
+ * use it to disable sibling items while work is pending.
+ * Returns `false` outside a `Menu.Root` / `ContextMenu.Root`.
+ */
+export declare function useMenuPending(): boolean;
+export declare function isThenable(value: unknown): value is Promise<unknown>;
+type RootWithPendingProps = {
+    onOpenChange?: (open: boolean, eventDetails: {
+        cancel: () => void;
+    }) => void;
+    actionsRef?: RefObject<RootActions | null>;
+    children?: ReactNode;
+};
+/**
+ * Wraps a Base UI menu root so async `Menu.Item` clicks can lock dismissal
+ * (outside press, Escape) until the promise settles.
+ */
+export declare function withMenuPendingRoot<P extends RootWithPendingProps>(BaseRoot: ComponentType<P>): ComponentType<P>;
+export type AsyncMenuItemClick = (event: ReactMouseEvent<HTMLElement>) => void | Promise<unknown>;
+/**
+ * Shared click handler for `Menu.Item` / `ContextMenu.Item` promise support.
+ * Returns whether the item should show its loading state.
+ */
+export declare function useAsyncMenuItem({ onClick, closeOnClick, loading, disabled, }: {
+    onClick?: AsyncMenuItemClick;
+    closeOnClick?: boolean;
+    loading?: boolean;
+    disabled?: boolean;
+}): {
+    inert: boolean;
+    blocked: boolean;
+    handleClick: (event: ReactMouseEvent<HTMLElement>) => void;
+};
+/** Menu-row spinner — keeps `data-menu-spinner` for the hide-siblings CSS. */
+export declare function MenuItemSpinner(): import("react").JSX.Element;
+export {};

package/dist/src/components/spinner/index.d.ts

@@ -0,0 +1 @@
+export { Spinner, SPINNER_SIZES, type SpinnerProps, type SpinnerSize, } from './spinner';

package/dist/src/components/spinner/spinner.d.ts

@@ -0,0 +1,32 @@
+import { ComponentProps } from 'react';
+/** Size axis — the ring scales with the surrounding control. */
+export declare const SPINNER_SIZES: {
+    sm: {
+        classes: string;
+        description: string;
+    };
+    md: {
+        classes: string;
+        description: string;
+    };
+    lg: {
+        classes: string;
+        description: string;
+    };
+};
+export type SpinnerSize = keyof typeof SPINNER_SIZES;
+export interface SpinnerProps extends Omit<ComponentProps<"svg">, "children"> {
+    /** Size variant. @default "md" */
+    size?: SpinnerSize;
+}
+/**
+ * Indeterminate loading ring — a hairline track with a quarter-circle arc
+ * rotating over it. The continuous 2px round-cap stroke matches Pho's
+ * hairline rings and Tabler icon language. Uses `currentColor`, so ink
+ * follows the parent (`text-pho-*`, white on overlays). Decorative by default
+ * (`aria-hidden`); pass `aria-label` when the spinner is the only loading cue.
+ */
+export declare function Spinner({ size, className, "aria-label": ariaLabel, "aria-hidden": ariaHidden, ...props }: SpinnerProps): import("react").JSX.Element;
+export declare namespace Spinner {
+    var displayName: string;
+}

package/dist/src/components/theme-toggle/index.d.ts

@@ -0,0 +1 @@
+export { ThemeToggle, getThemeMode, getThemePreference, setThemeMode, parseThemeMode, resolveThemeMode, THEME_STORAGE_KEY, type ThemeMode, type ResolvedTheme, type ThemeToggleProps, type ThemeToggleSize, } from './theme-toggle';

package/dist/src/components/theme-toggle/theme-toggle.d.ts

@@ -0,0 +1,81 @@
+import { HTMLAttributes } from 'react';
+/**
+ * Appearance preference — `device` follows `prefers-color-scheme`; `light` /
+ * `dark` force the scheme via `data-mode`.
+ */
+export type ThemeMode = "device" | "light" | "dark";
+/** Resolved color-scheme after applying a preference. */
+export type ResolvedTheme = "light" | "dark";
+/** Default `localStorage` key used by the docs site and this component. */
+export declare const THEME_STORAGE_KEY = "pho-mode";
+declare const THEME_SIZES: {
+    readonly xs: {
+        readonly track: "gap-px rounded-base p-0.5";
+        readonly item: "size-5.5 rounded-[calc(var(--radius-base)-2px)] [&>svg]:size-3";
+    };
+    readonly sm: {
+        readonly track: "gap-0.5 rounded-base p-0.5";
+        readonly item: "size-7 rounded-[calc(var(--radius-base)-2px)] [&>svg]:size-3.5";
+    };
+    readonly md: {
+        readonly track: "gap-0.5 rounded-base p-0.5";
+        readonly item: "size-8 rounded-[calc(var(--radius-base)-2px)] [&>svg]:size-4";
+    };
+    readonly lg: {
+        readonly track: "gap-1 rounded-base p-1";
+        readonly item: "size-9 rounded-[calc(var(--radius-base)-4px)] [&>svg]:size-5";
+    };
+};
+export type ThemeToggleSize = keyof typeof THEME_SIZES;
+export interface ThemeToggleProps extends Omit<HTMLAttributes<HTMLDivElement>, "children" | "color" | "onChange" | "defaultValue"> {
+    /** Controlled preference. */
+    mode?: ThemeMode;
+    /** Uncontrolled initial preference. @default "device" */
+    defaultMode?: ThemeMode;
+    /** Fired when the user picks a segment. */
+    onModeChange?: (mode: ThemeMode) => void;
+    /**
+     * Persist the preference under this `localStorage` key. Pass `null` to skip
+     * persistence. @default "pho-mode"
+     */
+    storageKey?: string | null;
+    /**
+     * Element that receives `data-mode="dark"`. Defaults to
+     * `document.documentElement`.
+     */
+    target?: HTMLElement | null | (() => HTMLElement | null);
+    /** Size variant. @default "md" */
+    size?: ThemeToggleSize;
+}
+/** Parse a stored preference; unknown / missing values fall back to `device`. */
+export declare function parseThemeMode(value: string | null | undefined): ThemeMode;
+/** Resolve a preference against the OS color-scheme. */
+export declare function resolveThemeMode(mode: ThemeMode, query?: {
+    matches: boolean;
+}): ResolvedTheme;
+/** Drop in-memory preference + media listener (tests / full remounts). */
+export declare function clearThemePreference(): void;
+/** Current document preference (memory, then storage, else `device`). */
+export declare function getThemePreference(storageKey?: string | null): ThemeMode;
+/** Read the resolved light/dark mode from an element (or `<html>`). */
+export declare function getThemeMode(target?: HTMLElement | null): ResolvedTheme;
+/**
+ * Apply an appearance preference: persist it, resolve against the OS when
+ * `device`, set `data-mode` on the target, and notify document-level toggles.
+ */
+export declare function setThemeMode(mode: ThemeMode, options?: {
+    target?: HTMLElement | null;
+    storageKey?: string | null;
+}): void;
+/**
+ * Segmented appearance control — Device / Light / Dark. Forces
+ * `data-mode="dark"` (or clears it) so Pho's `light-dark()` tokens follow
+ * `color-scheme`. `device` tracks `prefers-color-scheme`. Persists under
+ * `pho-mode` by default; pair with a blocking `<head>` script to avoid a
+ * flash (see docs).
+ */
+export declare function ThemeToggle({ mode: modeProp, defaultMode, onModeChange, storageKey, target, size, className, "aria-label": ariaLabel, ...props }: ThemeToggleProps): import("react").JSX.Element;
+export declare namespace ThemeToggle {
+    var displayName: string;
+}
+export {};

package/dist/src/sections/sidebar/sidebar.d.ts

@@ -15,16 +15,15 @@ import { AnchorHTMLAttributes, ButtonHTMLAttributes, ComponentProps, FC, ReactNo
 /** The rail itself — sticky, full-height, hairline right edge. */
 export declare const SIDEBAR_ROOT = "border-pho-secondary bg-pho-page sticky top-0 flex h-dvh w-64 shrink-0 flex-col border-r px-4 py-5";
 /** A nav row at rest and on hover. Active/inactive inks split below. */
-export declare const SIDEBAR_ITEM = "outline-pho-brand flex w-full cursor-pointer items-center gap-2 rounded-md px-2 py-1.5 text-left text-sm transition-colors focus-visible:outline-2 focus-visible:-outline-offset-1";
+export declare const SIDEBAR_ITEM = "outline-pho-brand flex w-full cursor-pointer items-center gap-2 rounded-sm px-2 py-1.5 text-left text-base transition-colors focus-visible:outline-2 focus-visible:-outline-offset-1";
 /**
  * Selected row — lifted onto the primary surface with the site hairline.
  * The icon carries the same ink as the label so the pair reads as one unit.
  */
-export declare const SIDEBAR_ITEM_ACTIVE = "bg-pho-primary text-pho-primary ring-pho-secondary font-medium ring-1 ring-inset *:data-icon:text-fg-pho-primary";
+export declare const SIDEBAR_ITEM_ACTIVE = "bg-pho-primary text-pho-primary ring-pho-secondary font-medium ring-1 ring-inset *:data-icon:text-pho-primary";
 /**
- * Resting row — secondary ink (75% alpha; tertiary at 50% fails contrast for
- * nav labels), ghost wash on hover. The icon tracks the label's ink at every
- * state instead of sitting on a fainter step.
+ * Resting row — secondary ink (75%), ghost wash on hover. Icon tracks the
+ * label's ink at every state.
  */
 export declare const SIDEBAR_ITEM_INACTIVE: string;
 interface RootProps extends ComponentProps<"aside"> {
@@ -38,7 +37,7 @@ declare function Header({ className, ...props }: ComponentProps<"div">): import(
 declare function Nav({ className, ...props }: ComponentProps<"nav">): import("react").JSX.Element;
 /** One titled cluster of nav rows: a `GroupLabel` followed by a `List`. */
 declare function Group({ className, ...props }: ComponentProps<"div">): import("react").JSX.Element;
-/** The cluster's caption — secondary ink; quaternary (30%) is illegible. */
+/** The cluster's caption — description ink, regular weight. */
 declare function GroupLabel({ className, ...props }: ComponentProps<"div">): import("react").JSX.Element;
 interface ListProps extends ComponentProps<"ul"> {
     /** Lay the rows out in two columns — for long, flat registries. */

package/dist/utils.js

@@ -1,5 +1,5 @@
 "use client";
-import { t as r } from "./chunks/cn-7uGUzCOM.js";
+import { t as r } from "./chunks/cn-DTiB6ek_.js";
 import { n as e, r as n, t as i } from "./chunks/link-provider-9TFNyDqO.js";
 import { t as a } from "./chunks/resolve-variant-CcD8iG5l.js";
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@photon-ai/pho-ui",
-  "version": "0.7.2",
+  "version": "1.0.1",
   "description": "Pho Design System — Photon's React component library, built on Base UI",
   "license": "UNLICENSED",
   "repository": {
@@ -65,6 +65,10 @@
       "types": "./dist/src/components/switch/index.d.ts",
       "import": "./dist/components/switch.js"
     },
+    "./components/theme-toggle": {
+      "types": "./dist/src/components/theme-toggle/index.d.ts",
+      "import": "./dist/components/theme-toggle.js"
+    },
     "./components/checkbox": {
       "types": "./dist/src/components/checkbox/index.d.ts",
       "import": "./dist/components/checkbox.js"
@@ -181,6 +185,10 @@
       "types": "./dist/src/components/kbd/index.d.ts",
       "import": "./dist/components/kbd.js"
     },
+    "./components/spinner": {
+      "types": "./dist/src/components/spinner/index.d.ts",
+      "import": "./dist/components/spinner.js"
+    },
     "./components/notification": {
       "types": "./dist/src/components/notification/index.d.ts",
       "import": "./dist/components/notification.js"

package/src/styles/fonts.css

@@ -1,19 +1,24 @@
 /**
- * Photon brand fonts, served from the shared asset CDN
- * (assets.photon.codes — public R2, versioned path, immutable caching, CORS
- * enabled). Import this and the fonts just work; no files to copy.
+ * Photon brand fonts. PolySans (commercial) is served from the shared asset
+ * CDN (assets.photon.codes — public R2, versioned path, immutable caching,
+ * CORS enabled). Azeret Mono is an open Google Font and comes from the Google
+ * Fonts CDN, which serves subsetted woff2 per script with `unicode-range`.
+ * Import this and the fonts just work; no files to copy.
  *
- * If your app must self-host (air-gapped, strict CSP without
- * `font-src https://assets.photon.codes`), skip this import and declare the
- * same four @font-face rules against your own /fonts/ paths — the theme only
- * references the family names.
+ * If your app must self-host (air-gapped, strict CSP without `font-src`
+ * covering https://assets.photon.codes and https://fonts.gstatic.com), skip
+ * this import and declare the same @font-face rules against your own /fonts/
+ * paths — the theme only references the family names.
  *
- * Roles (per photon.codes): PolySans is the voice — body/UI 400–500, headings
- * 550–600 (enable `ss02` on display text). Azeret Mono for code and small
+ * Roles (per photon.codes): PolySans is the voice — body at 400, UI/headings/
+ * hero slogans at 550 (`font-medium`); the `font-display` utility enables
+ * `ss02`. Azeret Mono for code and small
  * labels — always normal case: the system bans all-caps small text for
  * eyebrows, section titles, and descriptions. Instrument Serif (often
  * italic) is the editorial accent.
  */
+@import "https://fonts.googleapis.com/css2?family=Azeret+Mono:wght@100..900&display=swap";
+
 @font-face {
   font-family: "PolySans";
   src: url("https://assets.photon.codes/pho-ui/v1/PolySansVF.woff2")
@@ -23,15 +28,6 @@
   font-display: swap;
 }
 
-@font-face {
-  font-family: "Azeret Mono";
-  src: url("https://assets.photon.codes/pho-ui/v1/AzeretMono-VariableFont_wght.ttf")
-    format("truetype");
-  font-weight: 100 900;
-  font-style: normal;
-  font-display: swap;
-}
-
 @font-face {
   font-family: "Instrument Serif";
   src: url("https://assets.photon.codes/pho-ui/v1/InstrumentSerif-Regular.woff2")

package/src/styles/pho.css

@@ -25,10 +25,14 @@
   }
 
   /* Grayscale AA — macOS subpixel smoothing paints PolySans (and other VFs)
-     noticeably heavier at UI sizes. Matches the docs site's body.antialiased. */
+     noticeably heavier at UI sizes. Matches the docs site's body.antialiased.
+     font-synthesis: none — Instrument Serif ships only 400 (regular/italic)
+     and PolySans has no italic file; never let the browser fabricate a fake
+     bold or slant. A missing weight should look like a bug, not an imitation. */
   body {
     -webkit-font-smoothing: antialiased;
     -moz-osx-font-smoothing: grayscale;
+    font-synthesis: none;
   }
 }