@robert-stackflow/oneui 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.3.0 — 2026-10-28
+
+- AppShell 新增 brandName、brandIcon、brand、homePath、basePath 和 showHeader；支持无顶部栏的移动导航，可省略设置入口及侧栏折叠回调。普通点击向宿主传递内部路径，链接和新标签页使用完整基础路径。
+- 新增 createToaster 独立通知控制器，可由 React 组件外代码调用；ToastProvider 可接收 controller，保留原 useToast API 和单条通知替换行为。
+- IconPicker 支持 valuePrefix、自定义图标目录与 React 图标内容，保留存储 ID；统一字段、只读、禁用和表单值行为。
+- DatePicker 支持 timeZone、clearable、placeholder；指定时区影响今天/此刻及日历当天标记，输入的日历时间保持原值，不隐式转换为 UTC。
+- React/React DOM peer 范围调整为 ^19.2.0，独立消费验证覆盖 React 19.3.0 + TypeScript 5.9.3 和现有 React 19.3.1。
+- 两端示例增加前缀/自定义图标和指定时区日期示例；未迁移或修改 Moment 业务代码。
+- 修复极简深色导航选中文字过暗的问题。
+
 ## 0.2.0 — 2026-10-28
 
 - 新增 MessageDialog、ConfirmDialog、FormDialog 与统一 LoadingState，复用表单校验、异步提交、错误反馈和焦点管理。

package/README.md

@@ -45,7 +45,7 @@ export function App() {
 - 页面直接复用 Form / FormField / useFormState 的校验与提交状态、Alert 的错误反馈和 ConfirmDialog 的确认流程；避免另写原生表单、按钮样式或错误提示。
 - Button 支持 `href`，渲染标准链接并沿用按钮样式；禁用或加载时阻止导航。Card 传入 `onClick` 后渲染可通过键盘激活的按钮卡片。导航与业务回调由消费应用提供。
 - CSS Modules 随组件分发，由消费项目的构建工具处理。图标/字符目录通过标准 `new URL(..., import.meta.url)` 加载随包资源。
-- React 和 React DOM 为 peer dependencies，不打入组件包。当前验证版本为 React 19.3.1，浏览器验证使用 Chromium。
+- React 和 React DOM 为 peer dependencies（^19.2.0），不打入组件包。独立消费验证覆盖 React 19.3.1，以及 React 19.3.0 + TypeScript 5.9.3；浏览器验证使用 Chromium。
 
 ## 弹窗与加载状态
 
@@ -66,6 +66,35 @@ export function App() {
 
 菜单项间距统一为 `--menu-item-spacing: 1px`，菜单快捷键为靠右的纯文字提示，不预留空的指示器位置。Desktop 与 Web 共用示例：`/pickers?view=hierarchy`、`/forms?view=advanced`、`/data?view=hierarchy`；层级表格中的增删改仅更新示例内存数据。以上扩展从 0.2.0 起提供。
 
+## 接入现有应用（0.3.0）
+
+`AppShell` 默认仍显示 OneUI 品牌和顶部栏。可通过 `brandName`、`brandIcon` 设置品牌，或用 `brand` 替换完整品牌内容；`homePath` 指定宿主内部首页，`basePath="/admin"` 为实际链接添加基础路径。`onNavigate` 收到未加基础路径的内部路径，适合 React Router basename；Ctrl/Cmd 点击和新标签页使用完整 href。`showHeader={false}` 保留移动端浮动导航按钮。`settingsItem` 和 `onCollapsedChange` 可省略。自定义完整品牌内容由宿主负责紧凑侧栏适配。
+
+```tsx
+<AppShell brandName="Moment" brandIcon={<Brand />} homePath="/workbench"
+  basePath="/admin" showHeader={false} navigation={navigation}
+  active={active} title={title} onNavigate={navigate}>
+  {children}
+</AppShell>
+```
+
+组件外通知使用独立服务，并将同一实例交给 Provider；不需要在 API 模块调用 Hook。未挂载时保留最新消息；`notify` 返回该消息的关闭函数，旧消息的关闭函数不会关闭新消息。`dismiss` 触发关闭动画，`clear` 立即清除。默认仍只显示最新一条通知，多个控制器相互隔离；服务端渲染时应为每个应用/请求创建实例。
+
+```tsx
+// notifications.ts
+export const notifications = createToaster();
+export const notifyError = (error: Error) =>
+  notifications.notify(error.message, { tone: 'error' });
+// application root
+<ToastProvider controller={notifications}>{children}</ToastProvider>
+```
+
+`IconPicker valuePrefix="lucide:"` 将内置图标名转换为带前缀的存储值；`options` 可提供 `{ value, label, icon, keywords?, category? }` 自定义目录，选择后原样返回 value。自定义目录不加载内置图标资源，设置 options 时不应用 valuePrefix。`IconPickerProps`、`IconPickerOption` 可从根入口或组件子路径导入。
+
+`DatePicker mode="datetime" timeZone="Asia/Shanghai" seconds clearable` 使用指定 IANA 时区的今天/此刻，并支持清空及 placeholder。value 始终是 `YYYY-MM-DDTHH:mm[:ss]` 日历字段字符串；时区参数不把输入值变成时间戳，也不校验夏令时缺口/重复时间。定时发布、UTC 换算和时区歧义规则由宿主业务负责。无 timeZone 时继续使用设备本地时间。
+
+分类迁移时，如原应用父子分类独立选择，使用 `TreeSelect multiple checkStrictly`；图片上传的 EXIF/GPS、接口结果转换、串行策略（concurrency=1）与未保存状态属于宿主逻辑。
+
 ## 构建与打包
 
 在仓库根目录运行 `npm run pack:ui`。源码工作区供两端即时开发使用；发布内容单独生成到本目录 `dist`，含 ESM、TypeScript 声明、CSS 和资源。构建使用干净的临时目录并检查所有包内引用，成功后替换 dist，避免旧文件混入。`dist/package.json` 只导出生成内容。

package/components/AppShell.d.ts

@@ -14,17 +14,24 @@ export declare function ShellHeader({ title, collapsed, onToggle, onMenu, action
     windowControls?: ReactNode;
     draggable?: boolean;
 }): import("react").JSX.Element;
-export declare function AppShell({ navigation, settingsItem, active, title, collapsed, onCollapsedChange, onNavigate, children, headerActions, sidebarFooter, windowControls, draggable, }: {
+export interface AppShellProps {
     navigation: readonly NavigationItem[];
-    settingsItem: NavigationItem;
+    settingsItem?: NavigationItem;
     active: string;
     title: string;
     collapsed?: boolean;
-    onCollapsedChange(value: boolean): void;
+    onCollapsedChange?(value: boolean): void;
     onNavigate(path: string): void;
     children: ReactNode;
     headerActions?: ReactNode;
     sidebarFooter?: ReactNode;
     windowControls?: ReactNode;
     draggable?: boolean;
-}): import("react").JSX.Element;
+    brandName?: string;
+    brandIcon?: ReactNode;
+    brand?: ReactNode;
+    homePath?: string;
+    basePath?: string;
+    showHeader?: boolean;
+}
+export declare function AppShell({ navigation, settingsItem, active, title, collapsed, onCollapsedChange, onNavigate, children, headerActions, sidebarFooter, windowControls, draggable, brandName, brandIcon, brand, homePath, basePath, showHeader, }: AppShellProps): import("react").JSX.Element;

package/components/AppShell.js

@@ -1,5 +1,9 @@
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
-import { useEffect, useRef, useState } from "react";
+import {
+  useEffect,
+  useRef,
+  useState
+} from "react";
 import { Layers2, Menu, PanelLeftClose, PanelLeftOpen } from "lucide-react";
 import { Drawer } from "./Drawer.js";
 import { IconButton } from "./IconButton.js";
@@ -63,10 +67,24 @@ function AppShell({
   headerActions,
   sidebarFooter,
   windowControls,
-  draggable = false
+  draggable = false,
+  brandName = "OneUI",
+  brandIcon = /* @__PURE__ */ jsx(Layers2, { size: 20 }),
+  brand,
+  homePath = "/",
+  basePath = "",
+  showHeader = true
 }) {
   const [mobile, setMobile] = useState(false);
   const scroll = useRef(null);
+  const base = basePath.replace(/^\/+|\/+$/g, ""), href = (path) => (base ? "/" + base : "") + (path.startsWith("/") ? path : "/" + path);
+  const navigate = (event, path) => {
+    if (event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey)
+      return;
+    event.preventDefault();
+    onNavigate(path);
+    setMobile(false);
+  };
   useEffect(() => {
     setMobile(false);
     scroll.current?.scrollTo({ top: 0 });
@@ -74,16 +92,10 @@ function AppShell({
   const item = (n) => /* @__PURE__ */ jsxs(
     "a",
     {
-      href: n.path,
+      href: href(n.path),
       "aria-current": active === n.id ? "page" : void 0,
       title: collapsed ? n.label : void 0,
-      onClick: (e) => {
-        if (e.button === 0 && !e.metaKey && !e.ctrlKey && !e.shiftKey && !e.altKey) {
-          e.preventDefault();
-          onNavigate(n.path);
-          setMobile(false);
-        }
-      },
+      onClick: (event) => navigate(event, n.path),
       children: [
         n.icon,
         /* @__PURE__ */ jsx("span", { children: n.label })
@@ -92,59 +104,72 @@ function AppShell({
     n.id
   );
   const nav = /* @__PURE__ */ jsxs(Fragment, { children: [
-    /* @__PURE__ */ jsxs(
+    /* @__PURE__ */ jsx(
       "a",
       {
-        href: "/",
+        href: href(homePath),
         className: s.brand,
-        "aria-label": "OneUI \u9996\u9875",
-        onClick: (e) => {
-          e.preventDefault();
-          onNavigate("/");
-          setMobile(false);
-        },
-        children: [
-          /* @__PURE__ */ jsx("span", { className: s.mark, children: /* @__PURE__ */ jsx(Layers2, { size: 20 }) }),
-          /* @__PURE__ */ jsx("strong", { children: "OneUI" })
-        ]
+        "aria-label": brandName + " \u9996\u9875",
+        onClick: (event) => navigate(event, homePath),
+        children: brand ?? /* @__PURE__ */ jsxs(Fragment, { children: [
+          /* @__PURE__ */ jsx("span", { className: s.mark, children: brandIcon }),
+          /* @__PURE__ */ jsx("strong", { children: brandName })
+        ] })
       }
     ),
     /* @__PURE__ */ jsx("nav", { "aria-label": "\u4E3B\u5BFC\u822A", className: s.navigation, children: navigation.map(item) }),
-    /* @__PURE__ */ jsxs("div", { className: s.bottom, children: [
-      /* @__PURE__ */ jsx("nav", { "aria-label": "\u8BBE\u7F6E", className: s.navigation, children: item(settingsItem) }),
+    (settingsItem || sidebarFooter) && /* @__PURE__ */ jsxs("div", { className: s.bottom, children: [
+      settingsItem && /* @__PURE__ */ jsx("nav", { "aria-label": "\u8BBE\u7F6E", className: s.navigation, children: item(settingsItem) }),
       sidebarFooter
     ] })
   ] });
-  return /* @__PURE__ */ jsxs("div", { className: s.shell, "data-collapsed": collapsed, children: [
-    /* @__PURE__ */ jsx("a", { className: s.skip, href: "#main", children: "\u8DF3\u8F6C\u5230\u5185\u5BB9" }),
-    /* @__PURE__ */ jsx("aside", { className: s.sidebar, children: nav }),
-    /* @__PURE__ */ jsx(
-      Drawer,
-      {
-        placement: "left",
-        size: 280,
-        open: mobile,
-        onClose: () => setMobile(false),
-        title: "\u5BFC\u822A",
-        children: /* @__PURE__ */ jsx("div", { className: s.mobileNav, children: nav })
-      }
-    ),
-    /* @__PURE__ */ jsxs("div", { className: s.workspace, children: [
-      /* @__PURE__ */ jsx(
-        ShellHeader,
-        {
-          title,
-          collapsed,
-          onToggle: () => onCollapsedChange(!collapsed),
-          onMenu: () => setMobile(true),
-          actions: headerActions,
-          windowControls,
-          draggable
-        }
-      ),
-      /* @__PURE__ */ jsx("main", { ref: scroll, id: "main", tabIndex: -1, className: s.main, children: /* @__PURE__ */ jsx("div", { className: s.page, children }) })
-    ] })
-  ] });
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      className: s.shell,
+      "data-collapsed": collapsed,
+      "data-header": showHeader,
+      children: [
+        /* @__PURE__ */ jsx("a", { className: s.skip, href: "#main", children: "\u8DF3\u8F6C\u5230\u5185\u5BB9" }),
+        /* @__PURE__ */ jsx("aside", { className: s.sidebar, children: nav }),
+        /* @__PURE__ */ jsx(
+          Drawer,
+          {
+            placement: "left",
+            size: 280,
+            open: mobile,
+            onClose: () => setMobile(false),
+            title: "\u5BFC\u822A",
+            children: /* @__PURE__ */ jsx("div", { className: s.mobileNav, children: nav })
+          }
+        ),
+        /* @__PURE__ */ jsxs("div", { className: s.workspace, children: [
+          showHeader ? /* @__PURE__ */ jsx(
+            ShellHeader,
+            {
+              title,
+              collapsed,
+              onToggle: onCollapsedChange ? () => onCollapsedChange(!collapsed) : void 0,
+              onMenu: () => setMobile(true),
+              actions: headerActions,
+              windowControls,
+              draggable
+            }
+          ) : /* @__PURE__ */ jsx(
+            IconButton,
+            {
+              className: `${s.mobileToggle} ${s.floatingNavigation}`,
+              label: "\u6253\u5F00\u5BFC\u822A",
+              variant: "ghost",
+              onClick: () => setMobile(true),
+              children: /* @__PURE__ */ jsx(Menu, { size: 18 })
+            }
+          ),
+          /* @__PURE__ */ jsx("main", { ref: scroll, id: "main", tabIndex: -1, className: s.main, children: /* @__PURE__ */ jsx("div", { className: s.page, children }) })
+        ] })
+      ]
+    }
+  );
 }
 export {
   AppShell,

package/components/AppShell.module.css

@@ -78,7 +78,7 @@
 }
 .navigation a[aria-current="page"] {
   background: var(--selected);
-  color: var(--accent);
+  color: var(--navigation-selected-color, var(--accent));
 }
 .bottom {
   display: flex;
@@ -172,6 +172,15 @@
 .mobileToggle {
   display: none;
 }
+.floatingNavigation {
+  position: fixed;
+  z-index: 50;
+  top: 12px;
+  left: 12px;
+  background: var(--surface);
+  border: 1px solid var(--line);
+  box-shadow: var(--shadow-sm);
+}
 .mobileNav {
   display: flex;
   flex-direction: column;
@@ -219,6 +228,9 @@
   .page {
     padding: 28px 24px 40px;
   }
+  .shell[data-header="false"] .page {
+    padding-top: 64px;
+  }
 }
 @media (max-width: 540px) {
   .page {

package/components/Calendar.d.ts

@@ -6,5 +6,6 @@ export type CalendarProps = DateConstraints & {
     range?: DateRange;
     preview?: string;
     onHover?(value: string): void;
+    today?: string;
 };
-export declare function Calendar({ value, onChange, range, preview, onHover, minDate, maxDate, disabledDate, }: CalendarProps): import("react").JSX.Element;
+export declare function Calendar({ value, onChange, range, preview, onHover, minDate, maxDate, disabledDate, today, }: CalendarProps): import("react").JSX.Element;

package/components/Calendar.js

@@ -20,14 +20,15 @@ function Calendar({
   onHover,
   minDate,
   maxDate,
-  disabledDate
+  disabledDate,
+  today = dateKey(/* @__PURE__ */ new Date())
 }) {
   const constraints = { minDate, maxDate, disabledDate };
   const [month, setMonth] = useState(
-    () => readDate(boundedDate(value, constraints))
+    () => readDate(boundedDate(value || today, constraints))
   ), [view, setView] = useState("days"), [focused, setFocused] = useState(value);
   const grid = useRef(null), choices = useRef(null), pending = useRef(null), pendingView = useRef(false);
-  const year = month.getFullYear(), index = month.getMonth(), start = (calendarDate(year, index).getDay() + 6) % 7, base = Math.floor(year / 12) * 12, today = dateKey(/* @__PURE__ */ new Date());
+  const year = month.getFullYear(), index = month.getMonth(), start = (calendarDate(year, index).getDay() + 6) % 7, base = Math.floor(year / 12) * 12;
   const allowed = (key) => isDateAllowed(key, constraints);
   const monthAllowed = (y, m) => y >= 1 && y <= 9999 && !(minDate && parseDate(minDate) && dateKey(calendarDate(y, m + 1, 0)) < minDate) && !(maxDate && parseDate(maxDate) && dateKey(calendarDate(y, m)) > maxDate);
   const periodAllowed = (amount) => {

package/components/DatePicker.d.ts

@@ -8,6 +8,9 @@ export type SingleDatePickerProps = FieldOptions & DateConstraints & {
     label: string;
     mode?: Exclude<DatePickerMode, "range">;
     seconds?: boolean;
+    timeZone?: string;
+    clearable?: boolean;
+    placeholder?: string;
 };
 export type DatePickerProps = SingleDatePickerProps | (DateRangePickerProps & {
     mode: "range";

package/components/DatePicker.js

@@ -5,7 +5,7 @@ import { useId, useState } from "react";
 import { CalendarDays, Clock3 } from "lucide-react";
 import { Popover } from "./Popover.js";
 import { usePopover } from "./usePopover.js";
-import { Calendar, dateKey } from "./Calendar.js";
+import { Calendar } from "./Calendar.js";
 import { TimeColumns } from "./TimeColumns.js";
 import { Button } from "./Button.js";
 import s from "./DatePicker.module.css";
@@ -14,6 +14,7 @@ import {
   isDateAllowed
 } from "./dateConstraints.js";
 import { DateRangePicker } from "./DateRangePicker.js";
+import { calendarNow } from "./calendarNow.js";
 function DatePicker(props) {
   return props.mode === "range" ? /* @__PURE__ */ jsx(DateRangePicker, { ...props }) : /* @__PURE__ */ jsx(SingleDatePicker, { ...props });
 }
@@ -23,6 +24,9 @@ function SingleDatePicker({
   label,
   mode = "date",
   seconds = false,
+  timeZone,
+  clearable = false,
+  placeholder = "\u8BF7\u9009\u62E9",
   disabled,
   readOnly,
   name,
@@ -47,7 +51,8 @@ function SingleDatePicker({
     hint,
     ...aria
   });
-  const pop = usePopover(field.disabled || field.readOnly), id = useId(), [date, setDate] = useState(value.slice(0, 10) || dateKey(/* @__PURE__ */ new Date())), [time, setTime] = useState("00:00");
+  const now = () => calendarNow(timeZone), today = now().date;
+  const pop = usePopover(field.disabled || field.readOnly), id = useId(), [date, setDate] = useState(value.slice(0, 10) || today), [time, setTime] = useState("00:00");
   const close = pop.closeAndFocus;
   const show = () => {
     if (field.disabled || field.readOnly) return;
@@ -56,7 +61,7 @@ function SingleDatePicker({
       return;
     }
     setDate(
-      mode === "time" ? dateKey(/* @__PURE__ */ new Date()) : boundedDate(value.slice(0, 10), constraints)
+      mode === "time" ? now().date : boundedDate(value.slice(0, 10) || now().date, constraints)
     );
     setTime(
       (mode === "time" ? value : value.split(/[T ]/)[1]) || (seconds ? "00:00:00" : "00:00")
@@ -82,6 +87,7 @@ function SingleDatePicker({
         "aria-expanded": pop.open,
         "aria-haspopup": "dialog",
         "aria-controls": id,
+        "data-placeholder": !value || void 0,
         onClick: show,
         onKeyDown: (e) => {
           if (e.key === "ArrowDown" && !pop.open) {
@@ -90,7 +96,7 @@ function SingleDatePicker({
           }
         },
         children: [
-          /* @__PURE__ */ jsx("span", { children: value.replace("T", " ") || "\u8BF7\u9009\u62E9" }),
+          /* @__PURE__ */ jsx("span", { children: value.replace("T", " ") || placeholder }),
           mode === "time" ? /* @__PURE__ */ jsx(Clock3, {}) : /* @__PURE__ */ jsx(CalendarDays, {})
         ]
       }
@@ -119,6 +125,7 @@ function SingleDatePicker({
               Calendar,
               {
                 ...constraints,
+                today,
                 key: pop.open ? "open" : "closed",
                 value: date,
                 onChange: (next) => {
@@ -143,16 +150,14 @@ function SingleDatePicker({
           ] }),
           /* @__PURE__ */ jsxs("footer", { className: s.footer, children: [
             /* @__PURE__ */ jsx(
-              "button",
+              Button,
               {
+                variant: "ghost",
+                size: "small",
                 type: "button",
-                disabled: mode !== "time" && !isDateAllowed(dateKey(/* @__PURE__ */ new Date()), constraints),
+                disabled: mode !== "time" && !isDateAllowed(today, constraints),
                 onClick: () => {
-                  const now = /* @__PURE__ */ new Date(), nextDate = dateKey(now), nextTime = [
-                    now.getHours(),
-                    now.getMinutes(),
-                    ...seconds ? [now.getSeconds()] : []
-                  ].map((v) => String(v).padStart(2, "0")).join(":");
+                  const current = now(), nextDate = current.date, nextTime = current.time.slice(0, seconds ? 8 : 5);
                   if (mode !== "time" && !isDateAllowed(nextDate, constraints))
                     return;
                   setDate(nextDate);
@@ -165,16 +170,31 @@ function SingleDatePicker({
                 children: mode === "date" ? "\u4ECA\u5929" : "\u6B64\u523B"
               }
             ),
-            mode !== "date" && /* @__PURE__ */ jsx(
-              Button,
-              {
-                variant: "primary",
-                size: "small",
-                onClick: commit,
-                disabled: mode !== "time" && !isDateAllowed(date, constraints),
-                children: "\u786E\u5B9A"
-              }
-            )
+            (clearable || mode !== "date") && /* @__PURE__ */ jsxs("div", { className: s.rangeActions, children: [
+              clearable && /* @__PURE__ */ jsx(
+                Button,
+                {
+                  size: "small",
+                  variant: "ghost",
+                  disabled: !value,
+                  onClick: () => {
+                    onChange("");
+                    close();
+                  },
+                  children: "\u6E05\u7A7A"
+                }
+              ),
+              mode !== "date" && /* @__PURE__ */ jsx(
+                Button,
+                {
+                  variant: "primary",
+                  size: "small",
+                  onClick: commit,
+                  disabled: mode !== "time" && !isDateAllowed(date, constraints),
+                  children: "\u786E\u5B9A"
+                }
+              )
+            ] })
           ] })
         ]
       }

package/components/DatePicker.module.css

@@ -12,6 +12,9 @@
   height: 15px;
   color: var(--muted);
 }
+.trigger[data-placeholder="true"] > span {
+  color: var(--placeholder);
+}
 .body {
   display: flex;
 }

package/components/IconPicker.d.ts

@@ -1,6 +1,16 @@
-export declare function IconPicker({ value, onChange, label, disabled, }: {
+import { type ReactNode } from "react";
+import { type FieldOptions } from "./field";
+export type IconPickerOption = {
+    value: string;
+    label: string;
+    icon: ReactNode;
+    keywords?: string[];
+    category?: string;
+};
+export type IconPickerProps = FieldOptions & {
     value: string;
     onChange(value: string): void;
-    label?: string;
-    disabled?: boolean;
-}): import("react").JSX.Element;
+    options?: IconPickerOption[];
+    valuePrefix?: string;
+};
+export declare function IconPicker({ value, onChange, label, options, valuePrefix, ...props }: IconPickerProps): import("react").JSX.Element;

package/components/IconPicker.js

@@ -1,5 +1,5 @@
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
-import { useCallback, useMemo, useRef, useState } from "react";
+import { useCallback, useMemo, useState } from "react";
 import { Popover } from "./Popover.js";
 import { SearchField } from "./SearchField.js";
 import { CatalogIcon } from "./CatalogIcon.js";
@@ -10,16 +10,48 @@ import {
   VirtualPickerList
 } from "./VirtualPickerList.js";
 import { useIconCatalog, iconCategories } from "./iconCatalog.js";
+import { usePopover } from "./usePopover.js";
+import { useFieldControl, fieldTriggerProps } from "./field.js";
 import s from "./Picker.module.css";
 function IconPicker({
   value,
   onChange,
-  label = "\u56FE\u6807",
-  disabled = false
+  label,
+  options,
+  valuePrefix = "",
+  ...props
 }) {
-  const anchor = useRef(null), [open, setOpen] = useState(false), [query, setQuery] = useState("");
-  const { items, error, retry } = useIconCatalog(open);
+  const field = useFieldControl({ ...props, label }), pickerLabel = field.label || "\u56FE\u6807", blocked = field.disabled || field.readOnly, pop = usePopover(blocked), [query, setQuery] = useState("");
+  const name = valuePrefix && value.startsWith(valuePrefix) ? value.slice(valuePrefix.length) : value;
+  const selected = options?.find((option) => option.value === value);
+  const { items, error, retry } = useIconCatalog(
+    pop.open && options === void 0
+  );
   const groups = useMemo(() => {
+    if (options) {
+      const categories = /* @__PURE__ */ new Map();
+      for (const option of options) {
+        const category = option.category || "\u5168\u90E8";
+        if (!categories.has(category))
+          categories.set(category, {
+            id: category,
+            label: category,
+            items: []
+          });
+        categories.get(category).items.push({
+          id: option.value,
+          label: option.label,
+          content: option.icon,
+          search: [
+            option.value,
+            option.label,
+            category,
+            ...option.keywords || []
+          ].join(" ").toLowerCase()
+        });
+      }
+      return [...categories.values()];
+    }
     if (!items) return [];
     const indexed = items.map((icon) => ({
       id: icon.name,
@@ -40,43 +72,53 @@ function IconPicker({
         )
       })
     ).filter((group) => group.items.length);
-  }, [items]);
+  }, [items, options]);
   const choose = useCallback(
     (item) => {
-      onChange(item.id);
-      setOpen(false);
-      anchor.current?.focus();
+      if (blocked) return;
+      onChange(options ? item.id : valuePrefix + item.id);
+      pop.closeAndFocus();
     },
-    [onChange]
+    [onChange, blocked, options, valuePrefix, pop.closeAndFocus]
   );
   return /* @__PURE__ */ jsxs(Fragment, { children: [
     /* @__PURE__ */ jsx(
       SelectTrigger,
       {
-        ref: anchor,
-        expanded: open,
-        disabled,
-        "aria-label": label,
+        ...fieldTriggerProps(field),
+        "aria-label": pickerLabel,
+        ref: pop.anchor,
+        expanded: pop.open,
+        "data-readonly": field.readOnly || void 0,
         "aria-haspopup": "dialog",
-        onClick: () => setOpen((x) => !x),
+        onClick: pop.toggle,
         onKeyDown: (e) => {
           if (e.key === "ArrowDown" || e.key === "ArrowUp") {
             e.preventDefault();
-            setOpen(true);
+            pop.show();
           }
         },
-        icon: /* @__PURE__ */ jsx(CatalogIcon, { name: value }),
-        children: /* @__PURE__ */ jsx("span", { children: value || "\u9009\u62E9\u56FE\u6807" })
+        icon: options ? selected?.icon : /* @__PURE__ */ jsx(CatalogIcon, { name }),
+        children: /* @__PURE__ */ jsx("span", { children: selected?.label || name || "\u9009\u62E9\u56FE\u6807" })
+      }
+    ),
+    field.name && /* @__PURE__ */ jsx(
+      "input",
+      {
+        type: "hidden",
+        name: field.name,
+        value,
+        disabled: field.disabled
       }
     ),
     /* @__PURE__ */ jsx(
       Popover,
       {
-        open,
-        onClose: () => setOpen(false),
-        anchor,
+        open: pop.open,
+        onClose: pop.close,
+        anchor: pop.anchor,
         width: 470,
-        label: label + "\u9009\u62E9\u5668",
+        label: pickerLabel + "\u9009\u62E9\u5668",
         children: /* @__PURE__ */ jsxs("div", { className: s.panel, children: [
           /* @__PURE__ */ jsx(
             SearchField,
@@ -87,18 +129,18 @@ function IconPicker({
               onChange: setQuery
             }
           ),
-          error ? /* @__PURE__ */ jsx(Button, { onClick: retry, children: "\u91CD\u65B0\u52A0\u8F7D" }) : !items ? /* @__PURE__ */ jsx("div", { className: s.loading, children: /* @__PURE__ */ jsx(Spinner, { label: "\u52A0\u8F7D\u56FE\u6807" }) }) : /* @__PURE__ */ jsx(
+          options === void 0 && error ? /* @__PURE__ */ jsx(Button, { onClick: retry, children: "\u91CD\u65B0\u52A0\u8F7D" }) : options === void 0 && !items ? /* @__PURE__ */ jsx("div", { className: s.loading, children: /* @__PURE__ */ jsx(Spinner, { label: "\u52A0\u8F7D\u56FE\u6807" }) }) : /* @__PURE__ */ jsx(
             VirtualPickerList,
             {
               groups,
               query,
-              value,
+              value: options ? value : name,
               label: "\u56FE\u6807",
               onChoose: choose
             }
           ),
           /* @__PURE__ */ jsx("div", { className: s.footer, children: /* @__PURE__ */ jsxs("span", { children: [
-            items?.length || 0,
+            options?.length ?? items?.length ?? 0,
             " \u4E2A\u56FE\u6807"
           ] }) })
         ] })

package/components/ToastProvider.d.ts

@@ -1,4 +1,5 @@
 import { type ReactNode } from "react";
+import { type ToastController, type ToastNotify } from "./createToaster";
 export type ToastPosition = "top-left" | "top-center" | "top-right" | "bottom-left" | "bottom-center" | "bottom-right";
 export type ToastTone = "neutral" | "success" | "info" | "warning" | "error";
 export type ToastAction = {
@@ -27,9 +28,8 @@ export type ToastMessage = {
     options?: ToastOptions;
     closing?: boolean;
 };
-type Notify = (message: string, options?: ToastOptions | ToastTone) => () => void;
-export declare function ToastProvider({ children }: {
+export declare function ToastProvider({ children, controller, }: {
     children: ReactNode;
+    controller?: ToastController;
 }): import("react").JSX.Element;
-export declare const useToast: () => Notify;
-export {};
+export declare const useToast: () => ToastNotify;

package/components/ToastProvider.js

@@ -1,42 +1,39 @@
 import { jsx, jsxs } from "react/jsx-runtime";
 import {
   createContext,
-  useCallback,
   useContext,
-  useRef,
-  useState
+  useState,
+  useSyncExternalStore
 } from "react";
 import { useUIConfig } from "./UIProvider.js";
 import { Toast } from "./Toast.js";
+import {
+  createToaster
+} from "./createToaster.js";
 const Context = createContext(() => () => {
 });
-function ToastProvider({ children }) {
+const serverSnapshot = () => null;
+function ToastProvider({
+  children,
+  controller
+}) {
   const config = useUIConfig();
-  const [toast, setToast] = useState(null), counter = useRef(0);
-  const notify = useCallback((message, options) => {
-    const id = ++counter.current;
-    setToast({
-      message,
-      id,
-      options: typeof options === "string" ? { tone: options } : options
-    });
-    return () => setToast(
-      (current) => current?.id === id ? { ...current, closing: true } : current
-    );
-  }, []);
-  const clear = useCallback(
-    (id) => setToast((current) => current?.id === id ? null : current),
-    []
+  const [local] = useState(createToaster), source = controller || local;
+  const toast = useSyncExternalStore(
+    source.subscribe,
+    source.getSnapshot,
+    serverSnapshot
   );
-  return /* @__PURE__ */ jsxs(Context, { value: notify, children: [
+  return /* @__PURE__ */ jsxs(Context, { value: source.notify, children: [
     children,
     /* @__PURE__ */ jsx(
       Toast,
       {
         toast,
         position: toast?.options?.position || config.toastPosition,
-        onDismiss: clear
-      }
+        onDismiss: source.clear
+      },
+      source.id
     )
   ] });
 }

package/components/VirtualPickerList.d.ts

@@ -1,3 +1,4 @@
+import { type ReactNode } from "react";
 import { type LucideIconData } from "lucide-react";
 export type PickerCatalogItem = {
     id: string;
@@ -5,6 +6,7 @@ export type PickerCatalogItem = {
     search: string;
     glyph?: string;
     icon?: LucideIconData;
+    content?: ReactNode;
     variants?: {
         glyph: string;
         label: string;

package/components/VirtualPickerList.js

@@ -44,7 +44,7 @@ const Cell = memo(function Cell2({
         }
       },
       children: [
-        item.icon ? /* @__PURE__ */ jsx(Icon, { icon: item.icon }) : item.glyph,
+        item.content !== void 0 ? /* @__PURE__ */ jsx("span", { "aria-hidden": "true", children: item.content }) : item.icon ? /* @__PURE__ */ jsx(Icon, { icon: item.icon }) : item.glyph,
         item.variants && item.variants.length > 1 && /* @__PURE__ */ jsx("span", { className: s.variantMark, "aria-hidden": "true" })
       ]
     }

package/components/calendarNow.d.ts

@@ -0,0 +1,5 @@
+/** Calendar fields, not an instant conversion; keep entered wall-clock values intact. */
+export declare function calendarNow(timeZone?: string, instant?: Date): {
+    date: string;
+    time: string;
+};

package/components/calendarNow.js

@@ -0,0 +1,27 @@
+import { dateKey } from "./dateConstraints.js";
+function calendarNow(timeZone, instant = /* @__PURE__ */ new Date()) {
+  if (!timeZone)
+    return {
+      date: dateKey(instant),
+      time: [instant.getHours(), instant.getMinutes(), instant.getSeconds()].map((part2) => String(part2).padStart(2, "0")).join(":")
+    };
+  const parts = new Intl.DateTimeFormat("en-CA", {
+    timeZone,
+    numberingSystem: "latn",
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit",
+    hourCycle: "h23"
+  }).formatToParts(instant);
+  const part = (type) => parts.find((item) => item.type === type).value;
+  return {
+    date: part("year").padStart(4, "0") + "-" + part("month") + "-" + part("day"),
+    time: part("hour") + ":" + part("minute") + ":" + part("second")
+  };
+}
+export {
+  calendarNow
+};

package/components/createToaster.d.ts

@@ -0,0 +1,12 @@
+import type { ToastMessage, ToastOptions, ToastTone } from "./ToastProvider";
+export type ToastNotify = (message: string, options?: ToastOptions | ToastTone) => () => void;
+export interface ToastController {
+    readonly id: string;
+    notify: ToastNotify;
+    dismiss(id?: number): void;
+    clear(id?: number): void;
+    subscribe(listener: () => void): () => void;
+    getSnapshot(): ToastMessage | null;
+}
+/** An isolated notification service; no React or document access is required. */
+export declare function createToaster(): ToastController;

package/components/createToaster.js

@@ -0,0 +1,40 @@
+let nextController = 0;
+function createToaster() {
+  let current = null, counter = 0;
+  const listeners = /* @__PURE__ */ new Set();
+  const publish = (message) => {
+    if (current === message) return;
+    current = message;
+    listeners.forEach((listener) => listener());
+  };
+  const dismiss = (id = current?.id) => {
+    if (current && current.id === id && !current.closing)
+      publish({ ...current, closing: true });
+  };
+  return {
+    id: "oneui-toast-" + ++nextController,
+    notify(message, options) {
+      const id = ++counter;
+      publish({
+        message,
+        id,
+        options: typeof options === "string" ? { tone: options } : options
+      });
+      return () => dismiss(id);
+    },
+    dismiss,
+    clear(id = current?.id) {
+      if (current?.id === id) publish(null);
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    getSnapshot: () => current
+  };
+}
+export {
+  createToaster
+};

package/components/index.d.ts

@@ -47,7 +47,7 @@ export { CharacterPicker } from "./CharacterPicker";
 export { DataTable } from "./DataTable";
 export { EmojiPicker } from "./EmojiPicker";
 export { FileTree } from "./FileTree";
-export { IconPicker } from "./IconPicker";
+export { IconPicker, type IconPickerProps, type IconPickerOption, } from "./IconPicker";
 export { LoadingOverlay } from "./LoadingOverlay";
 export { LoadingState } from "./LoadingState";
 export { Pagination } from "./Pagination";
@@ -143,10 +143,11 @@ export { ThemeProvider } from "./ThemeProvider";
 export type { UITheme, ColorMode } from "./ThemeProvider";
 export { ThemeStylePicker } from "./ThemeStylePicker";
 export { AppShell, ShellHeader } from "./AppShell";
-export type { NavigationItem } from "./AppShell";
+export type { NavigationItem, AppShellProps } from "./AppShell";
 export { SettingsLayout, SettingsCard } from "./SettingsLayout";
 export { AppearanceSettings } from "./AppearanceSettings";
 export { appearanceDefaults, normalizeAppearance } from "./appearance";
 export type { AppearancePreferences } from "./appearance";
 export { MessageDialog, ConfirmDialog, FormDialog } from "./DialogVariants";
 export { TreeTable, type TreeTableProps } from "./TreeTable";
+export { createToaster, type ToastController, type ToastNotify, } from "./createToaster";

package/components/index.js

@@ -43,7 +43,9 @@ import { CharacterPicker } from "./CharacterPicker.js";
 import { DataTable } from "./DataTable.js";
 import { EmojiPicker } from "./EmojiPicker.js";
 import { FileTree } from "./FileTree.js";
-import { IconPicker } from "./IconPicker.js";
+import {
+  IconPicker
+} from "./IconPicker.js";
 import { LoadingOverlay } from "./LoadingOverlay.js";
 import { LoadingState } from "./LoadingState.js";
 import { Pagination } from "./Pagination.js";
@@ -106,6 +108,9 @@ import { AppearanceSettings } from "./AppearanceSettings.js";
 import { appearanceDefaults, normalizeAppearance } from "./appearance.js";
 import { MessageDialog, ConfirmDialog, FormDialog } from "./DialogVariants.js";
 import { TreeTable } from "./TreeTable.js";
+import {
+  createToaster
+} from "./createToaster.js";
 export {
   Accordion,
   Alert,
@@ -216,6 +221,7 @@ export {
   UploadList,
   VirtualPickerList,
   appearanceDefaults,
+  createToaster,
   formatFileSize,
   normalizeAppearance,
   useFormState,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@robert-stackflow/oneui",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "OneUI React components, application shell and portable visual themes",
   "type": "module",
   "sideEffects": [
@@ -789,7 +789,12 @@
       "import": "./components/TreeTable.js",
       "default": "./components/TreeTable.js"
     },
-    "./TreeTable.module.css": "./components/TreeTable.module.css"
+    "./TreeTable.module.css": "./components/TreeTable.module.css",
+    "./createToaster": {
+      "types": "./components/createToaster.d.ts",
+      "import": "./components/createToaster.js",
+      "default": "./components/createToaster.js"
+    }
   },
   "files": [
     "components",
@@ -799,8 +804,8 @@
     "CHANGELOG.md"
   ],
   "peerDependencies": {
-    "react": "19.3.1",
-    "react-dom": "19.3.1"
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0"
   },
   "dependencies": {
     "lucide-react": "1.59.0"

package/styles/minimal.css

@@ -68,6 +68,7 @@
   --hover: #303030;
   --selected: #3a3a3a;
   --navigation: #181819;
+  --navigation-selected-color: var(--fg);
   --canvas: #202021;
   --field: #252526;
   --disabled: #686868;