@devxcrew/react-ui 0.0.0-stage → 0.1.7

package/src/design-system/page-registry.ts

@@ -0,0 +1,74 @@
+import type { DesignSystemPageDefinition } from './contracts'
+
+export const designSystemPages: readonly DesignSystemPageDefinition[] = [
+  {
+    defaultVariantId: 'v1',
+    description: 'A presentation-only sign-in page with application-owned authentication.',
+    id: 'login',
+    name: 'Login',
+    source: '@devxcrew/react-ui/blocks/auth',
+    variants: [
+      {
+        description: 'Centered CODEXSUN sign-in card for focused application entry.',
+        id: 'v1',
+        name: 'Login v1',
+      },
+      {
+        description: 'Split sign-in card with provider actions and a supporting visual panel.',
+        id: 'v2',
+        name: 'Login v2',
+      },
+    ],
+  },
+  {
+    defaultVariantId: 'v1',
+    description: 'A presentation-only account registration page.',
+    id: 'register',
+    name: 'Register',
+    source: '@devxcrew/react-ui/blocks/auth',
+    variants: [
+      {
+        description: 'Centered registration card for the standard account flow.',
+        id: 'v1',
+        name: 'Register v1',
+      },
+      {
+        description: 'Split registration page with workspace onboarding context.',
+        id: 'v2',
+        name: 'Register v2',
+      },
+    ],
+  },
+  {
+    defaultVariantId: 'default',
+    description: 'A focused account-recovery page that does not disclose account existence.',
+    id: 'forgot-password',
+    name: 'Forgot Password',
+    source: '@devxcrew/react-ui/blocks/auth',
+    variants: [
+      {
+        description: 'The package-owned account recovery page.',
+        id: 'default',
+        name: 'Forgot Password',
+      },
+    ],
+  },
+  {
+    defaultVariantId: 'default',
+    description: 'A full-page notification inbox with application-owned records and actions.',
+    id: 'notifications',
+    name: 'Notifications Page',
+    source: '@devxcrew/react-ui/blocks/notifications',
+    variants: [
+      {
+        description: 'The package-owned notification inbox page.',
+        id: 'default',
+        name: 'Notifications Page',
+      },
+    ],
+  },
+]
+
+export function getDesignSystemPage(pageId: string) {
+  return designSystemPages.find(({ id }) => id === pageId)
+}

package/src/design-system/selection.ts

@@ -0,0 +1,67 @@
+import { designSystemBlocks, getDesignSystemBlock } from "./block-registry";
+import { designSystemComponents, getDesignSystemComponent } from "./component-registry";
+import { designSystemPages, getDesignSystemPage } from "./page-registry";
+import { designSystemTemplates, getDesignSystemTemplate } from "./template-registry";
+import type { DesignSystemSelection, DesignSystemSelectionInput } from "./contracts";
+
+export const defaultDesignSystemSelection = createDesignSystemSelection();
+
+export function createDesignSystemSelection(input: DesignSystemSelectionInput = {}): DesignSystemSelection {
+  return Object.freeze({
+    blocks: Object.freeze(resolveSelections(designSystemBlocks, input.blocks)),
+    components: Object.freeze(resolveSelections(designSystemComponents, input.components)),
+    pages: Object.freeze(resolveSelections(designSystemPages, input.pages)),
+    templates: Object.freeze(resolveSelections(designSystemTemplates, input.templates)),
+  });
+}
+
+export function resolveDesignSystemComponentVariant(componentId: string, requestedVariantId?: string) {
+  const component = getDesignSystemComponent(componentId);
+  if (!component) throw new Error(`Unknown design-system component: ${componentId}`);
+  return resolveVariant(component, requestedVariantId);
+}
+
+export function resolveDesignSystemBlockVariant(blockId: string, requestedVariantId?: string) {
+  const block = getDesignSystemBlock(blockId);
+  if (!block) throw new Error(`Unknown design-system block: ${blockId}`);
+  return resolveVariant(block, requestedVariantId);
+}
+
+export function resolveDesignSystemPageVariant(pageId: string, requestedVariantId?: string) {
+  const page = getDesignSystemPage(pageId);
+  if (!page) throw new Error(`Unknown design-system page: ${pageId}`);
+  return resolveVariant(page, requestedVariantId);
+}
+
+export function resolveDesignSystemTemplateVariant(templateId: string, requestedVariantId?: string) {
+  const template = getDesignSystemTemplate(templateId);
+  if (!template) throw new Error(`Unknown design-system template: ${templateId}`);
+  return resolveVariant(template, requestedVariantId);
+}
+
+type VariantOwner = {
+  defaultVariantId: string;
+  id: string;
+  variants: readonly { id: string }[];
+};
+
+function resolveSelections(definitions: readonly VariantOwner[], requested: Readonly<Record<string, string>> = {}) {
+  rejectUnknownKeys(definitions, requested);
+  return Object.fromEntries(
+    definitions.map((definition) => [definition.id, resolveVariant(definition, requested[definition.id])]),
+  );
+}
+
+function resolveVariant(definition: VariantOwner, requestedVariantId?: string) {
+  const variantId = requestedVariantId ?? definition.defaultVariantId;
+  if (!definition.variants.some(({ id }) => id === variantId)) {
+    throw new Error(`Unknown ${definition.id} variant: ${variantId}`);
+  }
+  return variantId;
+}
+
+function rejectUnknownKeys(definitions: readonly VariantOwner[], requested: Readonly<Record<string, string>>) {
+  const knownIds = new Set(definitions.map(({ id }) => id));
+  const unknownId = Object.keys(requested).find((id) => !knownIds.has(id));
+  if (unknownId) throw new Error(`Unknown design-system selection: ${unknownId}`);
+}

package/src/design-system/template-registry.ts

@@ -0,0 +1,33 @@
+import type { DesignSystemTemplateDefinition } from "./contracts";
+
+export const designSystemTemplates: readonly DesignSystemTemplateDefinition[] = [
+  {
+    defaultVariantId: "v1",
+    description: "A configurable master-data list with table and card views plus a generated record form.",
+    id: "master-list",
+    name: "Master List",
+    source: "@devxcrew/react-ui/blocks/master-list",
+    variants: [
+      { id: "v1", name: "Master List v1", description: "A table-first master list page." },
+      { id: "v2", name: "Master List v2", description: "A dense Desk-style list with quick filters and row activity." },
+      { id: "v3", name: "Master List v3", description: "A dense Desk-style master list page." },
+      {
+        id: "v4",
+        name: "Master List v4",
+        description: "A full-width application header with a centered master-data table.",
+      },
+    ],
+  },
+  {
+    defaultVariantId: "default",
+    description: "A compact status system with semantic colors and a check mark for record states.",
+    id: "status",
+    name: "Status Template",
+    source: "@devxcrew/react-ui/components/status-badge",
+    variants: [{ id: "default", name: "Status", description: "Standard colored status badges for record lists." }],
+  },
+];
+
+export function getDesignSystemTemplate(id: string) {
+  return designSystemTemplates.find((template) => template.id === id);
+}

package/src/features/interface-topology/index.ts

@@ -0,0 +1,14 @@
+export type {
+  InterfaceTopologyController,
+  InterfaceTopologyDesk,
+  InterfaceTopologySection,
+} from './interface-topology.types'
+export { TopologyInspectionControl } from './topology-control'
+export { TopologyInspector } from './topology-inspector'
+export { TopologyMarker } from './topology-marker'
+export { TopologyRegion } from './topology-region'
+export { useInterfaceTopology } from './use-interface-topology'
+export {
+  validateInterfaceTopologyDesks,
+  validateInterfaceTopologySections,
+} from './use-interface-topology'

package/src/features/interface-topology/interface-topology.types.ts

@@ -0,0 +1,40 @@
+export type InterfaceTopologySection = {
+  description: string;
+  id: string;
+  name: string;
+  scope: string;
+  technicalName: string;
+};
+
+export type InterfaceTopologyDesk = {
+  id: string;
+  name: string;
+  sections: readonly InterfaceTopologySection[];
+};
+
+export type InterfaceTopologyRegionProps = {
+  'data-ito-highlighted': boolean;
+  'data-ito-section': string;
+};
+
+export type InterfaceTopologyController = {
+  activeDeskId: string;
+  allSections: readonly InterfaceTopologySection[];
+  close: () => void;
+  copyTechnicalName: (id: string) => void;
+  desks: readonly InterfaceTopologyDesk[];
+  highlightClassName: (id: string) => string;
+  inspect: (id: string) => void;
+  labelsVisible: boolean;
+  open: boolean;
+  regionProps: (id: string) => InterfaceTopologyRegionProps;
+  sections: readonly InterfaceTopologySection[];
+  selected: string;
+  select: (id: string) => void;
+  selectDesk: (id: string) => void;
+  setScope: (rootId: string | null) => void;
+  toggleHighlight: () => void;
+  toggleLabels: () => void;
+  toggleOpen: () => void;
+  highlighting: boolean;
+};

package/src/features/interface-topology/topology-control.tsx

@@ -0,0 +1,18 @@
+import { Tags } from 'lucide-react';
+import type { InterfaceTopologyController } from './interface-topology.types';
+
+export function TopologyInspectionControl({ topology }: { topology: InterfaceTopologyController }) {
+  const action = topology.open ? 'Close Topology Inspection' : 'Open Topology Inspection';
+  return (
+    <button
+      aria-label={action}
+      className="pointer-events-auto absolute right-4 bottom-8 z-10 grid size-9 cursor-pointer place-items-center rounded-md border border-border bg-white text-violet-700 shadow-sm transition hover:bg-violet-50 hover:text-violet-800 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-violet-500 data-[open=true]:bg-violet-100"
+      data-open={topology.open}
+      onClick={topology.toggleOpen}
+      title={action}
+      type="button"
+    >
+      <Tags aria-hidden="true" size={16} />
+    </button>
+  );
+}

package/src/features/interface-topology/topology-inspector.tsx

@@ -0,0 +1,228 @@
+import { Check, ChevronRight, Copy, Eye, EyeOff, Highlighter, X } from 'lucide-react';
+import { useEffect, useState } from 'react';
+import {
+  Select,
+  SelectContent,
+  SelectGroup,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '@devxcrew/react-ui/components/select';
+import type { InterfaceTopologyController, InterfaceTopologySection } from './interface-topology.types';
+
+export function TopologyInspector({ topology }: { topology: InterfaceTopologyController }) {
+  if (!topology.open) return null;
+  const selected = topology.sections.find(({ id }) => id === topology.selected) ?? topology.sections[0];
+  if (!selected) return null;
+
+  return (
+    <aside
+      aria-label="Interface Topology Overlay"
+      className="pointer-events-auto absolute top-4 right-14 bottom-20 flex w-88 max-w-[calc(100vw-4.5rem)] flex-col overflow-hidden rounded-xl border border-border bg-white text-neutral-950 shadow-xl"
+    >
+      <InspectorHeader topology={topology} />
+      <SelectedSectionDetails section={selected} topology={topology} />
+      <nav
+        aria-label="Topology sections"
+        className="min-h-0 flex-1 overflow-y-auto px-2 py-2 [scrollbar-color:#a78bfa_transparent] [scrollbar-width:thin] [&::-webkit-scrollbar-thumb]:rounded-full [&::-webkit-scrollbar-thumb]:bg-violet-400 [&::-webkit-scrollbar]:w-1"
+      >
+        {topology.sections
+          .filter((section) => isRootSection(section, topology.sections))
+          .map((section) => (
+            <TopologyGroup key={section.id} section={section} topology={topology} />
+          ))}
+      </nav>
+    </aside>
+  );
+}
+
+function SelectedSectionDetails({
+  section,
+  topology,
+}: {
+  section: InterfaceTopologySection;
+  topology: InterfaceTopologyController;
+}) {
+  const [copied, setCopied] = useState(false);
+
+  useEffect(() => setCopied(false), [section.id]);
+  useEffect(() => {
+    if (!copied) return;
+    const timer = window.setTimeout(() => setCopied(false), 1_500);
+    return () => window.clearTimeout(timer);
+  }, [copied]);
+
+  return (
+    <div className="border-b border-border px-3 py-3">
+      <strong className="block truncate text-sm">
+        {section.id} · {section.name}
+      </strong>
+      <button
+        aria-label={`Copy ${section.technicalName}`}
+        className="mt-1 flex w-full cursor-pointer items-center gap-2 rounded-md py-1 text-left text-violet-700 transition hover:bg-violet-50 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-violet-500"
+        onClick={() => {
+          topology.copyTechnicalName(section.id);
+          setCopied(true);
+        }}
+        title="Copy technical name"
+        type="button"
+      >
+        <code className="min-w-0 flex-1 break-all text-xs font-bold">{section.technicalName}</code>
+        {copied ? <Check aria-hidden="true" size={15} /> : <Copy aria-hidden="true" size={15} />}
+        <span className="sr-only" aria-live="polite">
+          {copied ? 'Copied' : ''}
+        </span>
+      </button>
+    </div>
+  );
+}
+
+function InspectorHeader({ topology }: { topology: InterfaceTopologyController }) {
+  return (
+    <header className="flex items-center gap-2 border-b border-border p-3">
+      {topology.desks.length > 1 ? (
+        <Select
+          items={topology.desks.map((desk) => ({ label: desk.name, value: desk.id }))}
+          onValueChange={(value) => {
+            if (value) topology.selectDesk(value);
+          }}
+          value={topology.activeDeskId}
+        >
+          <SelectTrigger aria-label="Select topology desk" className="min-w-0 flex-1" size="sm">
+            <SelectValue />
+          </SelectTrigger>
+          <SelectContent align="start">
+            <SelectGroup>
+              {topology.desks.map((desk) => (
+                <SelectItem key={desk.id} value={desk.id}>
+                  {desk.name}
+                </SelectItem>
+              ))}
+            </SelectGroup>
+          </SelectContent>
+        </Select>
+      ) : (
+        <span className="flex-1" />
+      )}
+      <div className="flex shrink-0 items-center gap-1">
+        <HeaderAction
+          active={topology.labelsVisible}
+          label={topology.labelsVisible ? 'Hide ITO labels' : 'Show ITO labels'}
+          onClick={topology.toggleLabels}
+        >
+          {topology.labelsVisible ? <Eye size={16} /> : <EyeOff size={16} />}
+        </HeaderAction>
+        <HeaderAction
+          active={topology.highlighting}
+          label="Toggle boundary highlighter"
+          onClick={topology.toggleHighlight}
+        >
+          <Highlighter size={16} />
+        </HeaderAction>
+        <HeaderAction label="Close Topology Inspection" onClick={topology.close}>
+          <X size={16} />
+        </HeaderAction>
+      </div>
+    </header>
+  );
+}
+
+function HeaderAction({
+  active = false,
+  children,
+  label,
+  onClick,
+}: {
+  active?: boolean;
+  children: React.ReactNode;
+  label: string;
+  onClick: () => void;
+}) {
+  return (
+    <button
+      aria-label={label}
+      aria-pressed={active}
+      className="grid size-8 cursor-pointer place-items-center rounded-md text-neutral-600 transition hover:bg-neutral-100 hover:text-neutral-950 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-violet-500 data-[active=true]:bg-violet-700 data-[active=true]:text-white"
+      data-active={active}
+      onClick={onClick}
+      title={label}
+      type="button"
+    >
+      {children}
+    </button>
+  );
+}
+
+function TopologyGroup({
+  section,
+  topology,
+}: {
+  section: InterfaceTopologySection;
+  topology: InterfaceTopologyController;
+}) {
+  const [collapsed, setCollapsed] = useState(false);
+  const children = topology.sections.filter(
+    ({ id }) => id.includes('.') && id.slice(0, id.lastIndexOf('.')) === section.id,
+  );
+  const selected = topology.selected === section.id;
+  const scopedToCurrentRegion = topology.sections.length < topology.allSections.length;
+  const expanded =
+    !collapsed &&
+    (scopedToCurrentRegion || (topology.highlighting && (selected || topology.selected.startsWith(`${section.id}.`))));
+  useEffect(() => setCollapsed(false), [topology.highlighting, topology.selected]);
+
+  return (
+    <div>
+      <div className="flex items-center gap-1">
+        <button
+          aria-expanded={children.length ? expanded : undefined}
+          className="grid min-w-0 flex-1 cursor-pointer grid-cols-[auto_1fr_auto] items-center gap-2 rounded-md px-2 py-1.5 text-left text-sm text-neutral-600 transition hover:bg-neutral-100 hover:text-neutral-950 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-violet-500 data-[selected=true]:bg-neutral-200 data-[selected=true]:text-violet-800"
+          data-selected={selected}
+          onClick={() => {
+            if (children.length && expanded) setCollapsed(true);
+            else {
+              setCollapsed(false);
+              topology.inspect(section.id);
+            }
+          }}
+          title={`Inspect ${section.technicalName}`}
+          type="button"
+        >
+          <b className="min-w-7 rounded bg-violet-700 px-1.5 py-1 text-center text-xs text-white">{section.id}</b>
+          <span className="truncate">{section.name}</span>
+          {children.length ? (
+            <ChevronRight className={expanded ? 'rotate-90' : ''} size={15} />
+          ) : selected ? (
+            <Check size={15} />
+          ) : null}
+        </button>
+        <button
+          aria-label={`Copy ${section.technicalName}`}
+          className="grid size-8 shrink-0 cursor-pointer place-items-center rounded-md text-violet-700 transition hover:bg-violet-50 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-violet-500"
+          onClick={(event) => {
+            event.stopPropagation();
+            topology.copyTechnicalName(section.id);
+          }}
+          onPointerDown={(event) => event.stopPropagation()}
+          title={`Copy ${section.technicalName}`}
+          type="button"
+        >
+          <Copy aria-hidden="true" size={14} />
+        </button>
+      </div>
+      {expanded ? (
+        <div className="ml-4 border-l border-border pl-1">
+          {children.map((child) => (
+            <TopologyGroup key={child.id} section={child} topology={topology} />
+          ))}
+        </div>
+      ) : null}
+    </div>
+  );
+}
+
+function isRootSection(section: InterfaceTopologySection, sections: readonly InterfaceTopologySection[]) {
+  if (!section.id.includes('.')) return true;
+  const parentId = section.id.slice(0, section.id.lastIndexOf('.'));
+  return !sections.some((candidate) => candidate.id === parentId);
+}

package/src/features/interface-topology/topology-marker.tsx

@@ -0,0 +1,47 @@
+import type { CSSProperties } from 'react';
+import type { InterfaceTopologyController } from './interface-topology.types';
+
+const itoAccent = 'hsl(265 85% 52% / 0.9)';
+const itoAccentSoft = 'hsl(265 92% 94% / 0.95)';
+
+export function TopologyMarker({ id, topology }: { id: string; topology: InterfaceTopologyController }) {
+  const section = topology.sections.find((candidate) => candidate.id === id);
+  if (!section || !topology.labelsVisible || !isLabelVisible(id, topology)) return null;
+  const selected = topology.open && topology.selected === id;
+  const isBanner = !id.includes('.');
+  const style = {
+    '--ito-sticker': itoAccent,
+    '--ito-sticker-soft': itoAccentSoft,
+  } as CSSProperties;
+
+  return (
+    <button
+      aria-label={`Inspect ${section.name}: ${section.technicalName}`}
+      className="absolute top-2 left-2 z-30 flex min-h-6 min-w-7 max-w-48 cursor-pointer items-center justify-center gap-1.5 rounded-md border border-white/60 bg-[var(--ito-sticker-soft)] px-1.5 text-xs font-extrabold text-[var(--ito-sticker)] shadow-lg backdrop-blur-md transition hover:-translate-y-0.5 hover:bg-[var(--ito-sticker)] hover:text-white focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring data-[selected=true]:bg-[var(--ito-sticker)] data-[selected=true]:text-white"
+      data-ito-marker={id}
+      data-selected={selected}
+      onClick={(event) => {
+        event.preventDefault();
+        event.stopPropagation();
+        topology.inspect(id);
+      }}
+      onPointerDown={(event) => event.stopPropagation()}
+      style={style}
+      title={`${id} · ${section.name} · ${section.technicalName}`}
+      type="button"
+    >
+      <span>{displayId(id)}</span>
+      {isBanner && <span className="truncate font-semibold">{section.name}</span>}
+    </button>
+  );
+}
+
+function displayId(id: string) {
+  return id.replace(/^[a-z]+/i, '').padStart(2, '0');
+}
+
+function isLabelVisible(id: string, topology: InterfaceTopologyController) {
+  if (!id.includes('.')) return true;
+  if (!topology.highlighting) return false;
+  return id === topology.selected || id.slice(0, id.lastIndexOf('.')) === topology.selected;
+}

package/src/features/interface-topology/topology-region.tsx

@@ -0,0 +1,44 @@
+import type { CSSProperties, ElementType, HTMLAttributes, ReactNode } from 'react';
+import { cn } from '../../lib/utils';
+import type { InterfaceTopologyController } from './interface-topology.types';
+import { TopologyMarker } from './topology-marker';
+
+export function TopologyRegion({
+  as: Component = 'section',
+  children,
+  className,
+  id,
+  topology,
+  ...props
+}: Omit<HTMLAttributes<HTMLElement>, 'id'> & {
+  as?: ElementType;
+  children: ReactNode;
+  className?: string;
+  id: string;
+  topology: InterfaceTopologyController;
+}) {
+  const regionProps = topology.regionProps(id);
+  const highlighted = regionProps['data-ito-highlighted'];
+  const style = {
+    ...props.style,
+    '--ito-sticker': 'hsl(265 85% 52% / 0.9)',
+  } as CSSProperties;
+
+  return (
+    <Component
+      className={cn('relative data-[ito-highlighted=true]:z-20', className)}
+      {...props}
+      {...regionProps}
+      style={style}
+    >
+      <TopologyMarker id={id} topology={topology} />
+      {children}
+      {highlighted ? (
+        <span
+          aria-hidden="true"
+          className="pointer-events-none absolute inset-0 z-40 rounded-[inherit] border-2 border-[var(--ito-sticker)]"
+        />
+      ) : null}
+    </Component>
+  );
+}