@open-mercato/ui 0.6.3-develop.3809.1.bde5459e65 → 0.6.3-develop.3811.1.be22750402

package/.turbo/turbo-build.log

@@ -1,3 +1,3 @@
 Generated lucide registry with 135 icons -> /home/runner/work/open-mercato/open-mercato/packages/ui/src/backend/icons/lucideRegistry.generated.tsx
-[build:ui] found 353 entry points
+[build:ui] found 354 entry points
 [build:ui] built successfully

package/AGENTS.md

@@ -4,6 +4,41 @@ UI usage patterns based on customers, sales, and staff modules. Use these defaul
 
 > **DS reference:** [`.ai/ds-rules.md`](../../.ai/ds-rules.md) — color tokens, typography, spacing, decision trees. **Component reference (variants/sizes/props/examples/MUST rules):** [`.ai/ui-components.md`](../../.ai/ui-components.md).
 
+## Always
+
+- Use existing UI primitives and backend components before creating new ones.
+- Use `CrudForm` for create/edit flows and dialog forms unless the task explicitly needs a custom host.
+- Use `DataTable` as the default list view, including portal list pages.
+- Use `apiCall`/`apiCallOrThrow` for backend and portal data calls.
+- Use `useGuardedMutation` for every write that cannot use `CrudForm`.
+- Use i18n keys and `useT()` for user-facing copy.
+- Keep UMES spot IDs, replacement handles, field/group IDs, and portal page metadata stable.
+- Follow `.ai/ds-rules.md` and `.ai/ui-components.md` for tokens, primitives, and component contracts.
+
+## Ask First
+
+- Ask before changing primitive APIs, DataTable/CrudForm contracts, portal shell behavior, frozen portal spots, or replacement handles.
+- Ask before creating a new primitive or backend component when an existing component might fit.
+- Ask before changing default interaction patterns for dialogs, bulk actions, row clicks, or portal navigation.
+
+## Never
+
+- Never use raw `<button>`, raw checkbox inputs, or raw `<Link>` styled as a button.
+- Never use raw `fetch` in UI data flows where `apiCall` is available.
+- Never hard-code user-facing strings.
+- Never use `window.confirm`; use the shared confirmation dialog.
+- Never add custom per-page progress bars for DataTable bulk work.
+- Never omit `page.meta.ts` for guarded portal pages.
+- Never gate wildcard feature arrays with `includes(...)` or `Set.has(...)`.
+
+## Validation Commands
+
+```bash
+yarn workspace @open-mercato/ui test
+yarn workspace @open-mercato/ui build
+yarn i18n:check
+```
+
 ## Reference Modules
 
 - Customers: `packages/core/src/modules/customers/backend/customers/people/create/page.tsx`, `…/people/page.tsx`, `…/components/detail/TaskForm.tsx`
@@ -45,7 +80,7 @@ When you need… use this. Details (variants, sizes, props, MUST rules) live in
 | Breadcrumb navigation (DS-aligned, slash/arrow/dot divider, ARIA correct) | `Breadcrumb` (with `BreadcrumbList` / `BreadcrumbItem` / `BreadcrumbLink` / `BreadcrumbPage` / `BreadcrumbStatic` / `BreadcrumbSeparator` / `BreadcrumbEllipsis`) | `@open-mercato/ui/primitives/breadcrumb` |
 | Wrap a `<Link>` as button | `Button asChild` / `IconButton asChild` | — |
 
-## Critical MUST rules (top of mind)
+## Critical Primitive Rules
 
 1. **NEVER use raw `<button>` or `<input type="checkbox">`** — always use the primitives. Native checkboxes get `accent-color: var(--accent-indigo)` as a safety net for legacy code, but new code MUST use `Checkbox`.
 2. **Always pass `type="button"` explicitly** on non-submit `Button`/`IconButton` — HTML defaults to `submit`.
@@ -119,7 +154,7 @@ import { Avatar, AvatarStack } from '@open-mercato/ui/primitives/avatar'
 // renders: JK · OZ · AN · +1
 ```
 
-### MUST rules
+### Usage Rules
 
 - NEVER render `<div className="rounded-full bg-muted ...">` for avatars — use `Avatar`
 - `size="sm"` uses `text-[9px]` — DS exception for tiny initials (same as notification badge count)
@@ -157,7 +192,7 @@ import { Kbd, KbdShortcut } from '@open-mercato/ui/primitives/kbd'
 </span>
 ```
 
-### MUST rules
+### Usage Rules
 
 - NEVER use raw `<span>` or `<code>` to display keyboard keys — use `Kbd`
 - Platform-specific keys (`⌘` vs `Ctrl`): detect with `navigator.platform` or use `Ctrl/⌘` text when cross-platform
@@ -220,7 +255,7 @@ const leadTagMap: TagMap<'customer' | 'hot' | 'inactive' | 'renewal'> = {
 <Tag variant={leadTagMap[tag.type]} dot>{tag.label}</Tag>
 ```
 
-### MUST rules
+### Usage Rules
 
 - NEVER hardcode colors on `Tag` — use variants only
 - Use `dot` for tags that represent a status-like category (Customer, Hot); omit for purely descriptive labels

package/dist/backend/detail/RecordNotFoundState.js

@@ -0,0 +1,39 @@
+"use client";
+import { jsx } from "react/jsx-runtime";
+import Link from "next/link";
+import { Button } from "@open-mercato/ui/primitives/button";
+import { ErrorMessage } from "./ErrorMessage.js";
+import { cn } from "@open-mercato/shared/lib/utils";
+import { useT } from "@open-mercato/shared/lib/i18n/context";
+function RecordNotFoundState({
+  label,
+  description,
+  backHref,
+  backLabel,
+  action,
+  className
+}) {
+  const t = useT();
+  const defaultAction = backHref ? /* @__PURE__ */ jsx(Button, { asChild: true, variant: "outline", size: "sm", children: /* @__PURE__ */ jsx(Link, { href: backHref, children: backLabel ?? t("ui.recordNotFound.backToList", "Back to list") }) }) : null;
+  return /* @__PURE__ */ jsx(
+    "div",
+    {
+      className: cn(
+        "flex flex-col items-center justify-center min-h-[50vh] px-4",
+        className
+      ),
+      children: /* @__PURE__ */ jsx(
+        ErrorMessage,
+        {
+          label,
+          description,
+          action: action ?? defaultAction
+        }
+      )
+    }
+  );
+}
+export {
+  RecordNotFoundState
+};
+//# sourceMappingURL=RecordNotFoundState.js.map

package/dist/backend/detail/RecordNotFoundState.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/backend/detail/RecordNotFoundState.tsx"],
+  "sourcesContent": ["\"use client\";\n\nimport * as React from \"react\";\nimport Link from \"next/link\";\nimport { Button } from \"@open-mercato/ui/primitives/button\";\nimport { ErrorMessage } from \"./ErrorMessage\";\nimport { cn } from \"@open-mercato/shared/lib/utils\";\nimport { useT } from \"@open-mercato/shared/lib/i18n/context\";\n\nexport type RecordNotFoundStateProps = {\n  label: string;\n  description?: string;\n  backHref?: string;\n  backLabel?: string;\n  action?: React.ReactNode;\n  className?: string;\n};\n\nexport function RecordNotFoundState({\n  label,\n  description,\n  backHref,\n  backLabel,\n  action,\n  className,\n}: RecordNotFoundStateProps) {\n  const t = useT();\n  const defaultAction = backHref ? (\n    <Button asChild variant=\"outline\" size=\"sm\">\n      <Link href={backHref}>{backLabel ?? t('ui.recordNotFound.backToList','Back to list')}</Link>\n    </Button>\n  ) : null;\n\n  return (\n    <div\n      className={cn(\n        \"flex flex-col items-center justify-center min-h-[50vh] px-4\",\n        className,\n      )}\n    >\n      <ErrorMessage\n        label={label}\n        description={description}\n        action={action ?? defaultAction}\n      />\n    </div>\n  );\n}\n"],
+  "mappings": ";AA6BM;AA1BN,OAAO,UAAU;AACjB,SAAS,cAAc;AACvB,SAAS,oBAAoB;AAC7B,SAAS,UAAU;AACnB,SAAS,YAAY;AAWd,SAAS,oBAAoB;AAAA,EAClC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,GAA6B;AAC3B,QAAM,IAAI,KAAK;AACf,QAAM,gBAAgB,WACpB,oBAAC,UAAO,SAAO,MAAC,SAAQ,WAAU,MAAK,MACrC,8BAAC,QAAK,MAAM,UAAW,uBAAa,EAAE,gCAA+B,cAAc,GAAE,GACvF,IACE;AAEJ,SACE;AAAA,IAAC;AAAA;AAAA,MACC,WAAW;AAAA,QACT;AAAA,QACA;AAAA,MACF;AAAA,MAEA;AAAA,QAAC;AAAA;AAAA,UACC;AAAA,UACA;AAAA,UACA,QAAQ,UAAU;AAAA;AAAA,MACpB;AAAA;AAAA,EACF;AAEJ;",
+  "names": []
+}

package/dist/backend/detail/index.js

@@ -3,6 +3,7 @@ export * from "./DetailFieldsSection.js";
 export * from "./LoadingMessage.js";
 export * from "./ErrorMessage.js";
 export * from "./AccessDeniedMessage.js";
+import { RecordNotFoundState } from "./RecordNotFoundState.js";
 export * from "./TabEmptyState.js";
 export * from "./CustomDataSection.js";
 export * from "./TagsSection.js";
@@ -28,6 +29,7 @@ export {
   AddressView,
   AddressesSection,
   NotesSection,
+  RecordNotFoundState,
   formatAddressJson,
   formatAddressLines,
   formatAddressString,

package/dist/backend/detail/index.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../src/backend/detail/index.ts"],
-  "sourcesContent": ["export * from './InlineEditors'\nexport * from './DetailFieldsSection'\nexport * from './LoadingMessage'\nexport * from './ErrorMessage'\nexport * from './AccessDeniedMessage'\nexport * from './TabEmptyState'\nexport * from './CustomDataSection'\nexport * from './TagsSection'\nexport { NotesSection, mapCommentSummary } from './NotesSection'\nexport type { NotesSectionProps, CommentSummary, SectionAction, TabEmptyStateConfig } from './NotesSection'\nexport { ActivitiesSection } from './ActivitiesSection'\nexport type {\n  ActivitiesSectionProps,\n  ActivitiesDataAdapter,\n  ActivitySummary,\n  ActivityCreatePayload,\n  ActivityUpdatePayload,\n  ActivityFormBaseValues,\n  ActivityFormSubmitPayload,\n} from './ActivitiesSection'\nexport { AddressesSection } from './AddressesSection'\nexport type { AddressesSectionProps, AddressDataAdapter, AddressSummary } from './AddressesSection'\nexport { default as AddressTiles } from './AddressTiles'\nexport type { AddressInput, AddressValue as AddressTileValue, Translator as AddressTilesTranslator } from './AddressTiles'\nexport { default as AddressEditor } from './AddressEditor'\nexport type {\n  AddressTypeOption,\n  AddressTypesAdapter,\n  AddressEditorDraft,\n  AddressEditorField,\n} from './AddressEditor'\nexport {\n  AddressView,\n  formatAddressJson,\n  formatAddressLines,\n  formatAddressString,\n} from './addressFormat'\nexport type {\n  AddressFormatStrategy,\n  AddressJsonShape,\n  AddressValue as AddressFormatValue,\n} from './addressFormat'\nexport * from './AttachmentMetadataDialog'\nexport * from './AttachmentDeleteDialog'\nexport * from './AttachmentsSection'\nexport * from './AttachmentVisualPreview'\n"],
-  "mappings": "AAAA,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,SAAS,cAAc,yBAAyB;AAEhD,SAAS,yBAAyB;AAUlC,SAAS,wBAAwB;AAEjC,SAAoB,WAAXA,gBAA+B;AAExC,SAAoB,WAAXA,gBAAgC;AAOzC;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AAMP,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;",
+  "sourcesContent": ["export * from './InlineEditors'\nexport * from './DetailFieldsSection'\nexport * from './LoadingMessage'\nexport * from './ErrorMessage'\nexport * from './AccessDeniedMessage'\nexport { RecordNotFoundState } from './RecordNotFoundState'\nexport type { RecordNotFoundStateProps } from './RecordNotFoundState'\nexport * from './TabEmptyState'\nexport * from './CustomDataSection'\nexport * from './TagsSection'\nexport { NotesSection, mapCommentSummary } from './NotesSection'\nexport type { NotesSectionProps, CommentSummary, SectionAction, TabEmptyStateConfig } from './NotesSection'\nexport { ActivitiesSection } from './ActivitiesSection'\nexport type {\n  ActivitiesSectionProps,\n  ActivitiesDataAdapter,\n  ActivitySummary,\n  ActivityCreatePayload,\n  ActivityUpdatePayload,\n  ActivityFormBaseValues,\n  ActivityFormSubmitPayload,\n} from './ActivitiesSection'\nexport { AddressesSection } from './AddressesSection'\nexport type { AddressesSectionProps, AddressDataAdapter, AddressSummary } from './AddressesSection'\nexport { default as AddressTiles } from './AddressTiles'\nexport type { AddressInput, AddressValue as AddressTileValue, Translator as AddressTilesTranslator } from './AddressTiles'\nexport { default as AddressEditor } from './AddressEditor'\nexport type {\n  AddressTypeOption,\n  AddressTypesAdapter,\n  AddressEditorDraft,\n  AddressEditorField,\n} from './AddressEditor'\nexport {\n  AddressView,\n  formatAddressJson,\n  formatAddressLines,\n  formatAddressString,\n} from './addressFormat'\nexport type {\n  AddressFormatStrategy,\n  AddressJsonShape,\n  AddressValue as AddressFormatValue,\n} from './addressFormat'\nexport * from './AttachmentMetadataDialog'\nexport * from './AttachmentDeleteDialog'\nexport * from './AttachmentsSection'\nexport * from './AttachmentVisualPreview'\n"],
+  "mappings": "AAAA,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;AACd,SAAS,2BAA2B;AAEpC,cAAc;AACd,cAAc;AACd,cAAc;AACd,SAAS,cAAc,yBAAyB;AAEhD,SAAS,yBAAyB;AAUlC,SAAS,wBAAwB;AAEjC,SAAoB,WAAXA,gBAA+B;AAExC,SAAoB,WAAXA,gBAAgC;AAOzC;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AAMP,cAAc;AACd,cAAc;AACd,cAAc;AACd,cAAc;",
   "names": ["default"]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/ui",
-  "version": "0.6.3-develop.3809.1.bde5459e65",
+  "version": "0.6.3-develop.3811.1.be22750402",
   "type": "module",
   "main": "./dist/index.js",
   "scripts": {
@@ -141,13 +141,13 @@
     "remark-gfm": "^4.0.1"
   },
   "peerDependencies": {
-    "@open-mercato/shared": "0.6.3-develop.3809.1.bde5459e65",
+    "@open-mercato/shared": "0.6.3-develop.3811.1.be22750402",
     "react": ">=18.0.0",
     "react-dom": ">=18.0.0",
     "react-is": ">=18.0.0"
   },
   "devDependencies": {
-    "@open-mercato/shared": "0.6.3-develop.3809.1.bde5459e65",
+    "@open-mercato/shared": "0.6.3-develop.3811.1.be22750402",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.1",

package/src/backend/AGENTS.md

@@ -2,15 +2,34 @@
 
 Use `@open-mercato/ui/backend` for all admin/backend page components. See `packages/ui/AGENTS.md` for full UI patterns.
 
-## MUST Rules
+## Always
 
 1. **MUST set stable `id` values on `RowActions` items** — use `edit`, `open`, `delete`, etc. DataTable resolves default row-click behavior from these ids
 2. **MUST use `apiCall`/`apiCallOrThrow`** from `@open-mercato/ui/backend/utils/apiCall` — never use raw `fetch`
 3. **MUST use `LoadingMessage`/`ErrorMessage`** from `@open-mercato/ui/backend/detail` for loading and error states
-4. **MUST NOT hard-code user-facing strings** — use `useT()` for all labels and messages
+4. **MUST use `useT()`** for all labels and messages
 5. **MUST use `useGuardedMutation` when not using `CrudForm`** — wrap every write operation (`POST`/`PUT`/`PATCH`/`DELETE`) in `runMutation({ operation, context, mutationPayload })` so global mutation injections (record locks, conflict UI, future guards) run consistently
-6. **MUST use `Button` or `IconButton`** for every interactive button — never use raw `<button>` elements. Use `IconButton` for icon-only buttons, `Button` for everything else. Always pass `type="button"` explicitly on non-submit buttons. See `packages/ui/AGENTS.md` → Button and IconButton Usage for full patterns and variant reference.
-7. **MUST treat missing records as a dedicated page-level state** — distinguish `notFound` from generic `error`, return early, and render a shared `ErrorMessage`-based state with a clear recovery action (for example, back to the owning list page). Do not render `CrudForm`, detail sections, tabs, or record actions when the record is missing.
+6. **MUST use `Button` or `IconButton`** for every interactive button. Use `IconButton` for icon-only buttons, `Button` for everything else. Always pass `type="button"` explicitly on non-submit buttons. See `packages/ui/AGENTS.md` → Button and IconButton Usage for full patterns and variant reference.
+7. **MUST treat missing records as a dedicated page-level state** — distinguish `notFound` from generic `error`, return early, and render a shared `ErrorMessage`-based state with a clear recovery action (for example, back to the owning list page).
+
+## Ask First
+
+- Ask before changing DataTable row-click defaults, UMES host surface IDs, CrudForm event behavior, or replacement handles.
+- Ask before introducing backend-page write flows that do not fit `CrudForm` or `useGuardedMutation`.
+
+## Never
+
+- Never use raw `fetch` from backend UI components.
+- Never hard-code user-facing strings.
+- Never use raw `<button>` elements.
+- Never render `CrudForm`, detail sections, tabs, or record actions when the record is missing.
+
+## Validation Commands
+
+```bash
+yarn workspace @open-mercato/ui test
+yarn workspace @open-mercato/ui build
+```
 
 ## DataTable Row-Click Behavior
 

package/src/backend/detail/RecordNotFoundState.tsx

@@ -0,0 +1,48 @@
+"use client";
+
+import * as React from "react";
+import Link from "next/link";
+import { Button } from "@open-mercato/ui/primitives/button";
+import { ErrorMessage } from "./ErrorMessage";
+import { cn } from "@open-mercato/shared/lib/utils";
+import { useT } from "@open-mercato/shared/lib/i18n/context";
+
+export type RecordNotFoundStateProps = {
+  label: string;
+  description?: string;
+  backHref?: string;
+  backLabel?: string;
+  action?: React.ReactNode;
+  className?: string;
+};
+
+export function RecordNotFoundState({
+  label,
+  description,
+  backHref,
+  backLabel,
+  action,
+  className,
+}: RecordNotFoundStateProps) {
+  const t = useT();
+  const defaultAction = backHref ? (
+    <Button asChild variant="outline" size="sm">
+      <Link href={backHref}>{backLabel ?? t('ui.recordNotFound.backToList','Back to list')}</Link>
+    </Button>
+  ) : null;
+
+  return (
+    <div
+      className={cn(
+        "flex flex-col items-center justify-center min-h-[50vh] px-4",
+        className,
+      )}
+    >
+      <ErrorMessage
+        label={label}
+        description={description}
+        action={action ?? defaultAction}
+      />
+    </div>
+  );
+}

package/src/backend/detail/index.ts

@@ -3,6 +3,8 @@ export * from './DetailFieldsSection'
 export * from './LoadingMessage'
 export * from './ErrorMessage'
 export * from './AccessDeniedMessage'
+export { RecordNotFoundState } from './RecordNotFoundState'
+export type { RecordNotFoundStateProps } from './RecordNotFoundState'
 export * from './TabEmptyState'
 export * from './CustomDataSection'
 export * from './TagsSection'