@portnet/ui 6.0.1 → 6.0.3

package/dist/esm/v2/patterns/PreviewDrawer.js

@@ -0,0 +1,153 @@
+import * as React from "react";
+import VisibilityIcon from "@mui/icons-material/Visibility";
+import Button from "../components/Button";
+import Drawer from "../components/Drawer";
+import KV from "../components/KV";
+import KVGrid from "../components/KVGrid";
+import { mergeLabels } from "../utils/mergeLabels";
+
+/**
+ * PreviewDrawer — Portnet UI v2 (pattern)
+ *
+ * §Preview Drawer of the Platform Mandatory UX Patterns: the summary of a
+ * listing row — status, key information, quick actions — shown WITHOUT leaving
+ * the listing.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * WHY THIS BELONGS IN THE LIBRARY (capability gap G-40)
+ *
+ * §Row Interaction and §Preview Drawer are both MUST, on EVERY listing page of
+ * the platform: rows must be clickable, and clicking one must open a preview
+ * carrying summary, status, main information and quick actions. That is not a
+ * per-module feature, it is the platform's listing contract — and the library
+ * shipped only `Drawer`, the empty shell.
+ *
+ * So each module assembled the same body by hand, and the copies drifted where
+ * it is least visible: `ms-ti-fe` renders its label/value block with
+ * `KVGrid` + `KV`, while `refonte-frontend` had built a local `<dl>` with its
+ * own two-column grid — the same concept, two renderings, which is precisely
+ * what R-2.1 forbids. That module's Area 3 pass had to correct it before this
+ * promotion could even be considered.
+ *
+ * >>> AND THE SHELL WITHOUT THE BODY IS WHAT MADE THE UNSAFE VERSION LOOK
+ * >>> REASONABLE. The promoted implementation had carried an
+ * >>> `as unknown as DemandeRow` assertion, because a single component was
+ * >>> generic over the row type while computing its DEFAULTS from one specific
+ * >>> type's fields. Its own comment recorded the consequence: without those
+ * >>> defaults "the drawer does not fail — it shows dashes and an Unknown
+ * >>> status, which is worse than an error because it is noticed late". The
+ * >>> split below is what removes the cast rather than hiding it: THIS
+ * >>> component reads NO field of `row`. It renders what it is given and hands
+ * >>> the row back to the host's callbacks. A business default therefore lives
+ * >>> in a host wrapper whose `row` is a concrete type, and neither half has to
+ * >>> assert anything. <<<
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ * VALUES, NOT ACCESSORS, AND THE REASON IS THE CLOSING ANIMATION.
+ * `title` / `status` / `items` are optional VALUES rather than
+ * `(row: T) => …` functions. Hosts pass them through a conditional spread
+ * (`{...(row ? { title: …, items: … } : {})}`), which requiring them would
+ * make invalid — the compiler cannot see that the spread always supplies the
+ * keys. The natural workaround, mounting the drawer only when a row exists,
+ * would UNMOUNT it on close and destroy `Drawer`'s 220 ms exit animation
+ * (Charter §08).
+ *
+ * Consequence accepted: a missing `title` is not a compile error, it falls back
+ * to `labels.fallbackTitle`. The gain is that the drawer can no longer PRETEND
+ * an arbitrary row is a particular business object.
+ *
+ * Renders nothing when `row` is null, so hosts can mount it unconditionally.
+ *
+ * Usage:
+ *
+ *   <PreviewDrawer<DemandeRow>
+ *     open={apercuOuvert}
+ *     onClose={fermer}
+ *     row={ligneApercu}
+ *     subtitle="Déclaration d'importation"
+ *     onOpenItem={consulter}
+ *     labels={{ open: "Consulter la demande" }}
+ *     {...(ligneApercu ? { title: ligneApercu.identifiant, items: fiche } : {})}
+ *   />
+ */
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+const DEFAULT_LABELS = Object.freeze({
+  /** Generic on purpose: the business verb+object belongs to the host (§9.2). */
+  open: "Consulter",
+  fallbackTitle: "Détail"
+});
+
+/** One label/value line of the summary sheet. */
+
+function PreviewDrawer({
+  open,
+  onClose,
+  row,
+  subtitle,
+  title,
+  status,
+  items,
+  minColumnWidth,
+  onOpenItem,
+  canOpenItem,
+  actions,
+  onPrev,
+  onNext,
+  hasPrev,
+  hasNext,
+  children,
+  labels
+}) {
+  const L = mergeLabels(DEFAULT_LABELS, labels);
+  if (!row) return null;
+  const canOpen = canOpenItem ? canOpenItem(row) : true;
+  const lines = items ?? [];
+  return /*#__PURE__*/_jsxs(Drawer, {
+    open: open,
+    onClose: onClose,
+    title: title ?? L.fallbackTitle,
+    ...(subtitle !== undefined ? {
+      subtitle
+    } : {}),
+    ...(status !== undefined ? {
+      status
+    } : {}),
+    ...(onPrev ? {
+      onPrev
+    } : {}),
+    ...(onNext ? {
+      onNext
+    } : {}),
+    ...(hasPrev !== undefined ? {
+      hasPrev
+    } : {}),
+    ...(hasNext !== undefined ? {
+      hasNext
+    } : {}),
+    actions: actions ?? (canOpen && onOpenItem ? /*#__PURE__*/_jsx(Button, {
+      icon: /*#__PURE__*/_jsx(VisibilityIcon, {}),
+      onClick: () => onOpenItem(row),
+      children: L.open
+    }) : null),
+    children: [lines.length > 0 && /*#__PURE__*/_jsx(KVGrid, {
+      ...(minColumnWidth !== undefined ? {
+        minColumnWidth
+      } : {}),
+      children: lines.map((line, index) => /*#__PURE__*/_jsx(KV
+      // Index-based key on purpose: `label` is a ReactNode, so it is
+      // not always a usable key, and this list is not reorderable —
+      // it is rebuilt whole per row (R-R.3's exception).
+      , {
+        label: line.label,
+        ...(line.value !== undefined ? {
+          value: line.value
+        } : {}),
+        ...(line.mono !== undefined ? {
+          mono: line.mono
+        } : {})
+      }, index))
+    }), children]
+  });
+}
+export default PreviewDrawer;
+//# sourceMappingURL=PreviewDrawer.js.map

package/dist/esm/v2/patterns/PreviewDrawer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PreviewDrawer.js","names":["React","VisibilityIcon","Button","Drawer","KV","KVGrid","mergeLabels","jsx","_jsx","jsxs","_jsxs","DEFAULT_LABELS","Object","freeze","open","fallbackTitle","PreviewDrawer","onClose","row","subtitle","title","status","items","minColumnWidth","onOpenItem","canOpenItem","actions","onPrev","onNext","hasPrev","hasNext","children","labels","L","canOpen","lines","undefined","icon","onClick","length","map","line","index","label","value","mono"],"sources":["../../../../src/lib/v2/patterns/PreviewDrawer.tsx"],"sourcesContent":["import * as React from \"react\";\r\nimport VisibilityIcon from \"@mui/icons-material/Visibility\";\r\nimport Button from \"../components/Button\";\r\nimport Drawer from \"../components/Drawer\";\r\nimport KV from \"../components/KV\";\r\nimport KVGrid from \"../components/KVGrid\";\r\nimport { mergeLabels } from \"../utils/mergeLabels\";\r\n\r\n/**\r\n * PreviewDrawer — Portnet UI v2 (pattern)\r\n *\r\n * §Preview Drawer of the Platform Mandatory UX Patterns: the summary of a\r\n * listing row — status, key information, quick actions — shown WITHOUT leaving\r\n * the listing.\r\n *\r\n * ─────────────────────────────────────────────────────────────────────────────\r\n * WHY THIS BELONGS IN THE LIBRARY (capability gap G-40)\r\n *\r\n * §Row Interaction and §Preview Drawer are both MUST, on EVERY listing page of\r\n * the platform: rows must be clickable, and clicking one must open a preview\r\n * carrying summary, status, main information and quick actions. That is not a\r\n * per-module feature, it is the platform's listing contract — and the library\r\n * shipped only `Drawer`, the empty shell.\r\n *\r\n * So each module assembled the same body by hand, and the copies drifted where\r\n * it is least visible: `ms-ti-fe` renders its label/value block with\r\n * `KVGrid` + `KV`, while `refonte-frontend` had built a local `<dl>` with its\r\n * own two-column grid — the same concept, two renderings, which is precisely\r\n * what R-2.1 forbids. That module's Area 3 pass had to correct it before this\r\n * promotion could even be considered.\r\n *\r\n * >>> AND THE SHELL WITHOUT THE BODY IS WHAT MADE THE UNSAFE VERSION LOOK\r\n * >>> REASONABLE. The promoted implementation had carried an\r\n * >>> `as unknown as DemandeRow` assertion, because a single component was\r\n * >>> generic over the row type while computing its DEFAULTS from one specific\r\n * >>> type's fields. Its own comment recorded the consequence: without those\r\n * >>> defaults \"the drawer does not fail — it shows dashes and an Unknown\r\n * >>> status, which is worse than an error because it is noticed late\". The\r\n * >>> split below is what removes the cast rather than hiding it: THIS\r\n * >>> component reads NO field of `row`. It renders what it is given and hands\r\n * >>> the row back to the host's callbacks. A business default therefore lives\r\n * >>> in a host wrapper whose `row` is a concrete type, and neither half has to\r\n * >>> assert anything. <<<\r\n * ─────────────────────────────────────────────────────────────────────────────\r\n *\r\n * VALUES, NOT ACCESSORS, AND THE REASON IS THE CLOSING ANIMATION.\r\n * `title` / `status` / `items` are optional VALUES rather than\r\n * `(row: T) => …` functions. Hosts pass them through a conditional spread\r\n * (`{...(row ? { title: …, items: … } : {})}`), which requiring them would\r\n * make invalid — the compiler cannot see that the spread always supplies the\r\n * keys. The natural workaround, mounting the drawer only when a row exists,\r\n * would UNMOUNT it on close and destroy `Drawer`'s 220 ms exit animation\r\n * (Charter §08).\r\n *\r\n * Consequence accepted: a missing `title` is not a compile error, it falls back\r\n * to `labels.fallbackTitle`. The gain is that the drawer can no longer PRETEND\r\n * an arbitrary row is a particular business object.\r\n *\r\n * Renders nothing when `row` is null, so hosts can mount it unconditionally.\r\n *\r\n * Usage:\r\n *\r\n *   <PreviewDrawer<DemandeRow>\r\n *     open={apercuOuvert}\r\n *     onClose={fermer}\r\n *     row={ligneApercu}\r\n *     subtitle=\"Déclaration d'importation\"\r\n *     onOpenItem={consulter}\r\n *     labels={{ open: \"Consulter la demande\" }}\r\n *     {...(ligneApercu ? { title: ligneApercu.identifiant, items: fiche } : {})}\r\n *   />\r\n */\r\n\r\nconst DEFAULT_LABELS = Object.freeze({\r\n  /** Generic on purpose: the business verb+object belongs to the host (§9.2). */\r\n  open: \"Consulter\",\r\n  fallbackTitle: \"Détail\",\r\n});\r\n\r\nexport interface PreviewDrawerLabels {\r\n  open?: string | undefined;\r\n  fallbackTitle?: string | undefined;\r\n}\r\n\r\n/** One label/value line of the summary sheet. */\r\nexport interface PreviewDrawerItem {\r\n  label: React.ReactNode;\r\n  value?: React.ReactNode | undefined;\r\n  /** Renders the value in the mono face — IDs, references, amounts (§2.2). */\r\n  mono?: boolean | undefined;\r\n}\r\n\r\nexport interface PreviewDrawerProps<T> {\r\n  open?: boolean | undefined;\r\n  onClose?: (() => void) | undefined;\r\n  /** The previewed row. `null` renders nothing. */\r\n  row: T | null;\r\n  /** What kind of thing this is. Host vocabulary (§9.4). */\r\n  subtitle?: React.ReactNode | undefined;\r\n  /** Falls back to `labels.fallbackTitle` — see the note on values vs accessors. */\r\n  title?: React.ReactNode | undefined;\r\n  /** Status chip. Build it from `Status` so it stays on the `--status-*` palette (R-2.2). */\r\n  status?: React.ReactNode | undefined;\r\n  /** The summary sheet. Rendered as `KVGrid` + `KV`. */\r\n  items?: readonly PreviewDrawerItem[] | undefined;\r\n  /** Track minimum of the summary grid, in px. Defaults to `KVGrid`'s own. */\r\n  minColumnWidth?: number | undefined;\r\n  /** Opens the full record. Without it, no default action is rendered. */\r\n  onOpenItem?: ((row: T) => void) | undefined;\r\n  /**\r\n   * Whether the open action applies to this row.\r\n   *\r\n   * Defaults to ALLOWED. This component knows no business status, so it cannot\r\n   * derive a masking rule — and inventing one would be worse than having none.\r\n   */\r\n  canOpenItem?: ((row: T) => boolean) | undefined;\r\n  /** Replaces the default action entirely. */\r\n  actions?: React.ReactNode | undefined;\r\n  onPrev?: (() => void) | undefined;\r\n  onNext?: (() => void) | undefined;\r\n  hasPrev?: boolean | undefined;\r\n  hasNext?: boolean | undefined;\r\n  /** Rendered under the summary sheet — tabs, documents, a nested grid. */\r\n  children?: React.ReactNode | undefined;\r\n  labels?: PreviewDrawerLabels | undefined;\r\n}\r\n\r\nfunction PreviewDrawer<T>({\r\n  open,\r\n  onClose,\r\n  row,\r\n  subtitle,\r\n  title,\r\n  status,\r\n  items,\r\n  minColumnWidth,\r\n  onOpenItem,\r\n  canOpenItem,\r\n  actions,\r\n  onPrev,\r\n  onNext,\r\n  hasPrev,\r\n  hasNext,\r\n  children,\r\n  labels,\r\n}: PreviewDrawerProps<T>) {\r\n  const L = mergeLabels(DEFAULT_LABELS, labels);\r\n\r\n  if (!row) return null;\r\n\r\n  const canOpen = canOpenItem ? canOpenItem(row) : true;\r\n  const lines: readonly PreviewDrawerItem[] = items ?? [];\r\n\r\n  return (\r\n    <Drawer\r\n      open={open}\r\n      onClose={onClose}\r\n      title={title ?? L.fallbackTitle}\r\n      {...(subtitle !== undefined ? { subtitle } : {})}\r\n      {...(status !== undefined ? { status } : {})}\r\n      {...(onPrev ? { onPrev } : {})}\r\n      {...(onNext ? { onNext } : {})}\r\n      {...(hasPrev !== undefined ? { hasPrev } : {})}\r\n      {...(hasNext !== undefined ? { hasNext } : {})}\r\n      actions={\r\n        actions ??\r\n        (canOpen && onOpenItem ? (\r\n          <Button icon={<VisibilityIcon />} onClick={() => onOpenItem(row)}>\r\n            {L.open}\r\n          </Button>\r\n        ) : null)\r\n      }\r\n    >\r\n      {lines.length > 0 && (\r\n        <KVGrid {...(minColumnWidth !== undefined ? { minColumnWidth } : {})}>\r\n          {lines.map((line, index) => (\r\n            <KV\r\n              // Index-based key on purpose: `label` is a ReactNode, so it is\r\n              // not always a usable key, and this list is not reorderable —\r\n              // it is rebuilt whole per row (R-R.3's exception).\r\n              key={index}\r\n              label={line.label}\r\n              {...(line.value !== undefined ? { value: line.value } : {})}\r\n              {...(line.mono !== undefined ? { mono: line.mono } : {})}\r\n            />\r\n          ))}\r\n        </KVGrid>\r\n      )}\r\n      {children}\r\n    </Drawer>\r\n  );\r\n}\r\n\r\nexport default PreviewDrawer;\r\n"],"mappings":"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","ignoreList":[]}