@djangocfg/ui-tools 2.1.417 → 2.1.419

package/src/tools/dev/api/ApiRefTable/ApiRefTable.tsx

@@ -0,0 +1,65 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+//
+// API reference / props table with per-token type colorization,
+// expand-on-click description rows, and an optional `Default` column.
+//
+// Port notes:
+//   - Type-token colors map to semantic tokens (CONTRACT §2, AUDIT §6):
+//     string→success, number→warning, boolean→info, function→destructive,
+//     reactnode→info, enum→categorical (chart-3 var), nullish→muted-fg,
+//     primary→primary.
+//   - Required marker switched from a trailing `?` (optional indicator
+//     in the source) to a leading `*` in `text-destructive` for required
+//     rows; optionals keep the muted `?`.
+//   - Default-value chip is monospace on `bg-muted/40 border-border`.
+//   - No nested providers (CONTRACT §5); no motion (CONTRACT §4).
+
+'use client';
+
+import * as React from 'react';
+import { cn } from '@djangocfg/ui-core/lib';
+import type { ApiRefTableProps } from './types';
+import { Row } from './components/Row';
+
+export function ApiRefTable({
+  title,
+  props: rows,
+  nameLabel = 'Prop',
+  showDefaults,
+  emptyMessage = 'No parameters.',
+  className,
+  ...rest
+}: ApiRefTableProps) {
+  const showDefault = showDefaults ?? rows.some((r) => r.defaultValue != null);
+
+  return (
+    <div
+      data-slot="api-ref-table"
+      className={cn(
+        'overflow-hidden rounded-xl border border-border bg-card shadow-sm',
+        className,
+      )}
+      {...rest}
+    >
+      {title && (
+        <div className="border-b border-border/40 px-4 py-3">
+          <h3 className="text-lg font-semibold tracking-tight text-foreground">{title}</h3>
+        </div>
+      )}
+      <div className="flex items-center gap-4 border-b border-border/40 bg-muted/40 px-4 py-2.5 text-sm font-medium text-muted-foreground">
+        <span className="min-w-[180px] shrink-0">{nameLabel}</span>
+        <span className="flex-1 min-w-0">Type</span>
+        {showDefault && <span className="min-w-[100px] shrink-0">Default</span>}
+        {/* spacer matching the chevron column to keep header cells aligned */}
+        <span className="size-4 shrink-0" aria-hidden="true" />
+      </div>
+      {rows.length === 0 ? (
+        <div className="px-4 py-6 text-center text-sm text-muted-foreground">
+          {emptyMessage}
+        </div>
+      ) : (
+        rows.map((prop) => <Row key={prop.name} prop={prop} showDefault={showDefault} />)
+      )}
+    </div>
+  );
+}

package/src/tools/dev/api/ApiRefTable/README.md

@@ -0,0 +1,31 @@
+# ApiRefTable
+
+Reference table for component props / function parameters. Per-token type colorization, optional default column, click-to-expand description + long-form type.
+
+```tsx
+import { ApiRefTable } from '@djangocfg/ui-tools/api-ref-table';
+
+<ApiRefTable
+  title="ButtonProps"
+  props={[
+    { name: 'variant', type: "'solid' | 'outline'", defaultValue: "'solid'", description: 'Visual variant.' },
+    { name: 'onClick', type: '(e: MouseEvent) => void', required: true },
+  ]}
+/>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `props` | `ApiProp[]` | — | Rows. Each row: `{ name, type, required?, defaultValue?, description?, fullType? }`. |
+| `title` | `string` | — | Heading above the column strip. |
+| `nameLabel` | `string` | `'Prop'` | Leftmost column header (e.g. `'Param'`, `'Field'`). |
+| `showDefaults` | `boolean` | auto | Render the `Default` column. Auto when any row has `defaultValue`. |
+| `emptyMessage` | `string` | `'No parameters.'` | Empty state. |
+
+Storybook: `apps/storybook/stories/ui-tools/dev/ApiRefTable.stories.tsx`
+
+---
+
+Adapted from jalcoui (MIT).

package/src/tools/dev/api/ApiRefTable/components/Row.tsx

@@ -0,0 +1,96 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+
+'use client';
+
+import * as React from 'react';
+import { cn } from '@djangocfg/ui-core/lib';
+import type { ApiProp } from '../types';
+import { TypeDisplay } from './TypeDisplay';
+
+interface RowProps {
+  prop: ApiProp;
+  showDefault: boolean;
+}
+
+/**
+ * Single parameter row. Click to expand `description` / `fullType` when
+ * either is present; otherwise the button is rendered disabled so the
+ * row stays keyboard-accessible but doesn't pretend to be interactive.
+ */
+export function Row({ prop, showDefault }: RowProps) {
+  const [open, setOpen] = React.useState(false);
+  const hasDetails = Boolean(prop.description || prop.fullType);
+
+  return (
+    <div className="border-b border-border/40 last:border-b-0" data-slot="api-ref-row">
+      <button
+        type="button"
+        onClick={() => hasDetails && setOpen((v) => !v)}
+        disabled={!hasDetails}
+        className={cn(
+          'flex w-full items-center gap-4 px-4 py-3 text-left transition-colors',
+          hasDetails && 'cursor-pointer hover:bg-muted/30',
+          !hasDetails && 'cursor-default',
+        )}
+        aria-expanded={hasDetails ? open : undefined}
+      >
+        <span className="min-w-[180px] shrink-0 font-mono text-sm">
+          <span className="text-foreground">{prop.name}</span>
+          {prop.required ? (
+            <span className="ml-0.5 text-destructive" aria-label="required">
+              *
+            </span>
+          ) : (
+            <span className="text-muted-foreground" aria-hidden="true">
+              ?
+            </span>
+          )}
+        </span>
+        <span className="flex-1 min-w-0">
+          <TypeDisplay type={prop.type} />
+        </span>
+        {showDefault && (
+          <code
+            className={cn(
+              'min-w-[100px] shrink-0 font-mono text-xs',
+              prop.defaultValue ? 'text-foreground' : 'text-muted-foreground',
+            )}
+            data-slot="api-ref-default"
+          >
+            {prop.defaultValue ?? '—'}
+          </code>
+        )}
+        {hasDetails && (
+          <svg
+            viewBox="0 0 24 24"
+            fill="none"
+            stroke="currentColor"
+            strokeWidth={2}
+            strokeLinecap="round"
+            strokeLinejoin="round"
+            aria-hidden="true"
+            className={cn(
+              'size-4 shrink-0 text-muted-foreground transition-transform',
+              open && 'rotate-180',
+            )}
+          >
+            <path d="m6 9 6 6 6-6" />
+          </svg>
+        )}
+      </button>
+      {open && hasDetails && (
+        <div className="space-y-2 border-t border-border/30 bg-muted/20 px-4 py-3">
+          {prop.description && (
+            <p className="text-sm text-muted-foreground">{prop.description}</p>
+          )}
+          {prop.fullType && (
+            <div className="flex items-baseline gap-6">
+              <span className="shrink-0 text-sm text-muted-foreground">Type</span>
+              <TypeDisplay type={prop.fullType} />
+            </div>
+          )}
+        </div>
+      )}
+    </div>
+  );
+}

package/src/tools/dev/api/ApiRefTable/components/TypeDisplay.tsx

@@ -0,0 +1,44 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+
+'use client';
+
+import * as React from 'react';
+import { cn } from '@djangocfg/ui-core/lib';
+import { TYPE_TAG_CLASSES } from '../types';
+import { classifyTypeToken, splitTypeSignature } from '../utils';
+
+interface TypeDisplayProps {
+  type: string;
+  className?: string;
+}
+
+/**
+ * Render a type signature with per-token semantic colorization. Splits
+ * on `|`, classifies each token via {@link classifyTypeToken}, and maps
+ * the classification to a semantic `text-*` token from
+ * {@link TYPE_TAG_CLASSES}.
+ */
+export function TypeDisplay({ type, className }: TypeDisplayProps) {
+  const parts = React.useMemo(() => splitTypeSignature(type), [type]);
+
+  return (
+    <span className={cn('font-mono text-sm', className)} data-slot="api-ref-type">
+      {parts.map((part, i) => {
+        const trimmed = part.trim();
+        if (trimmed === '|') {
+          return (
+            <span key={i} className="text-muted-foreground">
+              {' | '}
+            </span>
+          );
+        }
+        const tag = classifyTypeToken(trimmed);
+        return (
+          <span key={i} className={TYPE_TAG_CLASSES[tag]} data-type-tag={tag}>
+            {trimmed}
+          </span>
+        );
+      })}
+    </span>
+  );
+}

package/src/tools/dev/api/ApiRefTable/index.ts

@@ -0,0 +1,6 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+
+export { ApiRefTable } from './ApiRefTable';
+export { TYPE_TAG_CLASSES } from './types';
+export { classifyTypeToken, splitTypeSignature } from './utils';
+export type { ApiProp, ApiRefTableProps, TypeTag } from './types';

package/src/tools/dev/api/ApiRefTable/lazy.tsx

@@ -0,0 +1,21 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+
+'use client';
+
+import { createLazyComponent } from '../../../../common/lazy-wrapper';
+import type { ApiRefTableProps } from './types';
+
+export const LazyApiRefTable = createLazyComponent<ApiRefTableProps>(
+  () => import('./ApiRefTable').then((mod) => ({ default: mod.ApiRefTable })),
+  {
+    displayName: 'LazyApiRefTable',
+    fallback: (
+      <div
+        data-slot="api-ref-table-skeleton"
+        className="h-48 w-full animate-pulse rounded-xl border border-border bg-muted"
+      />
+    ),
+  },
+);
+
+export type { ApiRefTableProps, ApiProp, TypeTag } from './types';

package/src/tools/dev/api/ApiRefTable/types.ts

@@ -0,0 +1,82 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+
+import type * as React from 'react';
+
+/**
+ * Single parameter / prop entry rendered as one row of the table.
+ *
+ * The minimum required shape is `{ name, type }`. Everything else is
+ * optional metadata that toggles UI affordances:
+ *
+ * - `required` — when `false` (or omitted), the name is rendered with a
+ *   trailing `?` muted marker. When `true`, a `*` in `text-destructive`
+ *   marks the row.
+ * - `defaultValue` — surfaces a `Default` column cell rendered in
+ *   `font-mono` on a `bg-muted/40` chip.
+ * - `description` / `fullType` — expand-on-click body. The row is only
+ *   interactive when at least one of these is present.
+ */
+export interface ApiProp {
+  /** Prop / parameter identifier (left column). */
+  name: string;
+  /** Compact type signature, e.g. `string | number`. Rendered with per-token colorization. */
+  type: string;
+  /** When `true`, mark as required with a `*` destructive marker. Defaults to `false`. */
+  required?: boolean;
+  /** Default value, shown in a monospace chip. */
+  defaultValue?: string;
+  /** Short description, shown in the expanded body. */
+  description?: string;
+  /** Long/expanded type signature, shown in the expanded body. */
+  fullType?: string;
+}
+
+/**
+ * Semantic tag for a single type token (the bits between `|` separators).
+ * Maps to a `text-*` semantic token in {@link TYPE_TAG_CLASSES}.
+ */
+export type TypeTag =
+  | 'string'
+  | 'number'
+  | 'boolean'
+  | 'function'
+  | 'reactnode'
+  | 'enum'
+  | 'nullish'
+  | 'primary'
+  | 'other';
+
+/**
+ * Tailwind classes per type-tag. All resolve to semantic / categorical
+ * tokens — never raw color scales (CONTRACT §2, AUDIT §6).
+ *
+ * `enum` routes through the `chart-3` CSS variable so it follows the
+ * active theme preset's categorical palette rather than a status color.
+ */
+export const TYPE_TAG_CLASSES: Record<TypeTag, string> = {
+  string: 'text-success',
+  number: 'text-warning',
+  boolean: 'text-info',
+  function: 'text-destructive',
+  reactnode: 'text-info',
+  enum: 'text-[hsl(var(--chart-3))]',
+  nullish: 'text-muted-foreground',
+  primary: 'text-primary',
+  other: 'text-success',
+};
+
+export interface ApiRefTableProps extends Omit<React.ComponentProps<'div'>, 'children'> {
+  /** Heading rendered above the column header strip. */
+  title?: string;
+  /** Parameter / prop rows. */
+  props: ApiProp[];
+  /**
+   * Label for the leftmost column header. Defaults to `Prop`.
+   * Override for non-React contexts ("Param", "Field", "Argument").
+   */
+  nameLabel?: string;
+  /** Render the `Default` column. Defaults to `true` when any row has a `defaultValue`. */
+  showDefaults?: boolean;
+  /** Message shown when `props` is empty. Defaults to `No parameters.`. */
+  emptyMessage?: string;
+}

package/src/tools/dev/api/ApiRefTable/utils.ts

@@ -0,0 +1,42 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+
+import type { TypeTag } from './types';
+
+/**
+ * Classify a single type token (e.g. `string`, `number[]`, `MyType<X>`,
+ * `null`) into a semantic {@link TypeTag}. The classification is
+ * intentionally loose — it only sees the bare token and ignores generic
+ * parameters / array brackets / optional `?`.
+ */
+export function classifyTypeToken(token: string): TypeTag {
+  const base = token.replace(/[[\]?]/g, '').split('<')[0].trim().toLowerCase();
+
+  if (!base) return 'other';
+  if (base === 'string') return 'string';
+  if (base === 'number' || base === 'bigint') return 'number';
+  if (base === 'boolean' || base === 'true' || base === 'false') return 'boolean';
+  if (base === 'function' || base === '() => void' || base.endsWith('=> void')) return 'function';
+  if (base === 'reactnode' || base === 'react.reactnode' || base === 'jsx.element' || base === 'reactelement') {
+    return 'reactnode';
+  }
+  if (base === 'null' || base === 'undefined' || base === 'void' || base === 'never') {
+    return 'nullish';
+  }
+  // String literal like `"foo"` or `'bar'` → enum-ish categorical.
+  if ((base.startsWith('"') && base.endsWith('"')) || (base.startsWith("'") && base.endsWith("'"))) {
+    return 'enum';
+  }
+  // Numeric literal → also categorical (discriminated unions).
+  if (/^-?\d+(\.\d+)?$/.test(base)) return 'enum';
+
+  return 'other';
+}
+
+/**
+ * Split a compound type signature on `|` separators, preserving the
+ * separator tokens so the renderer can colorize the divider with the
+ * muted foreground.
+ */
+export function splitTypeSignature(type: string): string[] {
+  return type.split(/(\s*\|\s*)/).filter((part) => part.length > 0);
+}

package/src/tools/dev/{OpenapiViewer → api/OpenapiViewer}/components/DocsLayout/ApiIntroSection.tsx

@@ -2,7 +2,7 @@
 
 import React from 'react';
 
-import { MarkdownMessage } from '../../../MarkdownMessage';
+import { MarkdownMessage } from '../../../../code/MarkdownMessage';
 import type { ApiEndpoint, OpenApiInfo, OpenApiSchema } from '../../types';
 import { SchemaCopyMenu } from './SchemaCopyMenu';
 

package/src/tools/dev/{OpenapiViewer → api/OpenapiViewer}/components/DocsLayout/EndpointDoc/CodeSamples/index.tsx

@@ -1,6 +1,6 @@
 'use client';
 
-import PrettyCode from '../../../../../PrettyCode';
+import PrettyCode from '../../../../../../code/PrettyCode';
 import type { ApiEndpoint } from '../../../../types';
 import { useEndpointDocContext } from '../context';
 import { useEndpointDocStore } from '../store';

package/src/tools/dev/{OpenapiViewer → api/OpenapiViewer}/components/DocsLayout/EndpointDoc/Header/index.tsx

@@ -5,7 +5,7 @@ import React, { useCallback, useMemo, useState } from 'react';
 
 import { Button } from '@djangocfg/ui-core/components';
 
-import { MarkdownMessage } from '../../../../../MarkdownMessage';
+import { MarkdownMessage } from '../../../../../../code/MarkdownMessage';
 import type { ApiEndpoint } from '../../../../types';
 import { endpointToMarkdown } from '../../../../utils/schemaExport';
 import type { SectionId } from '../types';

package/src/tools/dev/{OpenapiViewer → api/OpenapiViewer}/components/DocsLayout/EndpointDoc/Responses/ResponseBody.tsx

@@ -4,24 +4,7 @@ import { useMemo } from 'react';
 
 import { CopyButton } from '@djangocfg/ui-core/components';
 
-import JsonTree from '../../../../../../data/JsonTree';
-
-// Compact, read-only JsonTree config. Docs longread is space-constrained
-// so we ship less chrome than the interactive ``ResponsePanel`` — copy
-// button lives outside the tree (on the row header) and collection-info
-// stays on so long arrays don't silently truncate.
-const EXAMPLE_JSON_TREE_CONFIG = {
-    maxAutoExpandDepth: 2,
-    maxAutoExpandArrayItems: 5,
-    maxAutoExpandObjectKeys: 8,
-    maxStringLength: 160,
-    collectionLimit: 25,
-    showCollectionInfo: true,
-    showExpandControls: false,
-    showActionButtons: false,
-    preserveKeyOrder: true,
-    className: 'border-0 rounded-none',
-} as const;
+import { JsonTree } from '../../../../../../../data/JsonTree';
 
 interface ResponseBodyProps {
     example: string;
@@ -60,11 +43,14 @@ export function ResponseBody({ example, contentType }: ResponseBodyProps) {
                 </CopyButton>
             </div>
             {parsed != null ? (
+                // Docs longread is space-constrained: no toolbar (Copy
+                // lives on the row header above), no border (host owns
+                // it), shallow auto-expand.
                 <JsonTree
-                    title=""
                     data={parsed}
-                    mode="compact"
-                    config={EXAMPLE_JSON_TREE_CONFIG}
+                    toolbar="never"
+                    bordered={false}
+                    defaultExpandedDepth={1}
                 />
             ) : (
                 <pre className="p-3 text-[11px] font-mono text-foreground/70 whitespace-pre-wrap break-all leading-relaxed">

package/src/tools/dev/{OpenapiViewer → api/OpenapiViewer}/components/shared/RequestPanel.tsx

@@ -11,7 +11,7 @@ import {
 } from '@djangocfg/ui-core/components';
 import { cn } from '@djangocfg/ui-core/lib';
 
-import PrettyCode from '../../../PrettyCode';
+import PrettyCode from '../../../../code/PrettyCode';
 import { usePlaygroundContext } from '../../context/PlaygroundContext';
 import { findApiKeyById, isValidJson, parseRequestHeaders } from '../../utils';
 import { resolveAbsolute } from '../../utils/url';

package/src/tools/dev/{OpenapiViewer → api/OpenapiViewer}/components/shared/ResponsePanel/PrettyView.tsx

@@ -1,25 +1,9 @@
 'use client';
 
-import JsonTree from '../../../../../data/JsonTree';
-import PrettyCode from '../../../../PrettyCode';
+import { JsonTree } from '../../../../../../data/JsonTree';
+import PrettyCode from '../../../../../code/PrettyCode';
 import type { DetectedContent } from './types';
 
-// JsonTree config — same shape as the interactive docs example view
-// but with ``showActionButtons: false`` because the copy button in the
-// StatusBar already covers that flow.
-const JSON_TREE_CONFIG = {
-    maxAutoExpandDepth: 2,
-    maxAutoExpandArrayItems: 10,
-    maxAutoExpandObjectKeys: 5,
-    maxStringLength: 200,
-    collectionLimit: 50,
-    showCollectionInfo: true,
-    showExpandControls: true,
-    showActionButtons: false,
-    preserveKeyOrder: true,
-    className: 'border-0 rounded-none',
-} as const;
-
 interface PrettyViewProps {
     /** Parsed JSON tree when the body was JSON. */
     treeData: unknown;
@@ -35,7 +19,17 @@ interface PrettyViewProps {
  *  scroll, no floating toolbar fighting the surrounding layout. */
 export function PrettyView({ treeData, rawText, detected }: PrettyViewProps) {
     if (detected.kind === 'json' && treeData != null) {
-        return <JsonTree title="Response Body" data={treeData} config={JSON_TREE_CONFIG} />;
+        // StatusBar already exposes "Copy", so we drop the action from
+        // the toolbar — only expand/search remain. `bordered={false}` +
+        // host pane owns the frame.
+        return (
+            <JsonTree
+                title="Response Body"
+                data={treeData}
+                actions={['search', 'expand']}
+                bordered={false}
+            />
+        );
     }
     if (!rawText) {
         return (

package/src/tools/dev/{OpenapiViewer → api/OpenapiViewer}/components/shared/ResponsePanel/types.ts

@@ -1,4 +1,4 @@
-import type { Language } from '../../../../PrettyCode';
+import type { Language } from '../../../../../code/PrettyCode';
 
 /** Panels the user can switch between in the response view.
  *

package/src/tools/dev/{OpenapiViewer → api/OpenapiViewer}/lazy.tsx

@@ -11,7 +11,7 @@
  */
 
 import * as React from 'react';
-import { createLazyComponent } from '../../../components';
+import { createLazyComponent } from '../../../../common';
 import { PlaygroundProvider } from './context/PlaygroundContext';
 import type { ApiKey, PlaygroundConfig, SchemaSource } from './types';
 

package/src/tools/dev/api/RequestViewer/README.md

@@ -0,0 +1,33 @@
+# RequestViewer
+
+HTTP request inspector. Tabs for headers / body / timing. Method + status pills routed through `lib/http` (`statusColor`, `methodColor`) so colors match OpenapiViewer.
+
+The viewer never fetches — pass an already-executed `NetworkRequest`.
+
+```tsx
+import { RequestViewer } from '@djangocfg/ui-tools/request-viewer';
+
+<RequestViewer
+  request={{
+    method: 'POST',
+    url: 'https://api.example.com/v1/users',
+    status: 201,
+    requestHeaders: [{ name: 'Content-Type', value: 'application/json' }],
+    responseBody: '{"id":"u_42"}',
+    duration: 142,
+  }}
+/>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `request` | `NetworkRequest` | — | Captured request: `method`, `url`, `status`, headers, body, timing, etc. |
+| `defaultTab` | `'headers' \| 'body' \| 'timing'` | `'headers'` | Initial active tab. |
+
+Storybook: `apps/storybook/stories/ui-tools/dev/RequestViewer.stories.tsx`
+
+---
+
+Adapted from jalcoui (MIT).