@djangocfg/widget-code 0.1.1

package/src/pretty-code/README.md

@@ -0,0 +1,81 @@
+# PrettyCode
+
+Syntax-highlighted code block. Prism-powered, dark-by-default surface.
+
+## Why dark by default
+
+PrettyCode renders on a fixed dark surface (`#0d1117` + `vsDark` palette)
+regardless of the host theme — the same convention as GitHub, VSCode,
+ChatGPT, Slack. Syntax highlighting ships its own contrast model
+(keyword / string / number / comment) that flattens to low-contrast
+pastels when forced onto a light UI surface.
+
+The surface is intentionally **not** a semantic token. Semantic tokens
+(`--primary`, `--accent`, `--card`) describe UI affordances; code
+display is data, not UI.
+
+## Structure
+
+```
+PrettyCode/
+├── PrettyCode.client.tsx       # Main component (Highlight + dark surface)
+├── registerPrismLanguages.ts   # Lazy-load extra grammars (bash, ruby, java, php)
+├── index.tsx                   # Public re-export
+└── lazy.tsx                    # Lazy-loaded export
+```
+
+## Usage
+
+```tsx
+import { PrettyCode } from '@djangocfg/widget-code/pretty-code';
+
+<PrettyCode data={sourceCode} language="typescript" />
+
+// Inline snippet (used in markdown rendering)
+<PrettyCode data={`const x = 1`} language="ts" inline />
+
+// Capped at 50 visible lines, scrolls if longer
+<PrettyCode data={longBlob} language="json" maxLines={50} />
+
+// Chrome-less variant — embed inside another scroll container
+<PrettyCode data={src} language="bash" variant="plain" />
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `data` | `string \| object` | — | Code string. Objects are `JSON.stringify`d. |
+| `language` | `Language` | — | Prism language id. Unknown → plain text. |
+| `mode` | `'dark' \| 'light'` | `'dark'` | Palette override. Default is always dark (see "Why dark"). |
+| `inline` | `boolean` | `false` | Render as inline `<code>` (no card / toolbar). |
+| `variant` | `'card' \| 'plain'` | `'card'` | `plain` strips border, background, and toolbar. |
+| `isCompact` | `boolean` | `false` | 12px font instead of 14px. |
+| `maxLines` | `number` | `undefined` | When set, block scrolls past this many lines. |
+| `customBg` | `string` | — | Tailwind class to override the dark surface. |
+| `scrollIsolation` | `boolean` | `true` | Block scroll capture until clicked (long snippets). |
+| `className` | `string` | — | Extra classes on the wrapper. |
+
+## When to override `mode`
+
+Almost never. The dark default is correct for ~all cases. Pass
+`mode="light"` only for deliberate light-on-light renders (e.g. PDF
+export targeting a printed page). The surface falls back to
+`bg-card` semantic token in that mode.
+
+## Supported languages
+
+Out of the box: `javascript`, `typescript`, `python`, `json`, `css`,
+`markup` (html/xml), `sql`, `yaml`, `markdown`, `go`.
+
+Lazy-loaded on first use: `bash`/`shell`, `ruby`, `java`, `php`.
+Lazy load is tracked through `useEnsurePrismLanguages()` — the
+component re-renders once the grammar resolves.
+
+Unknown languages fall back to plain text (no highlighting, no error).
+
+## Storybook
+
+`UI Tools / Code / PrettyCode` — `Playground`, `TypeScript`, `Json`,
+`Python`, `Bash`, `Sql`, `Yaml`, `LongFileWithScroll`, `Inline`,
+`Compact`, `LightMode`, `PlainVariant`.

package/src/pretty-code/index.tsx

@@ -0,0 +1,72 @@
+/**
+ * PrettyCode Component - Dynamic Import Wrapper
+ *
+ * Lazy loads the heavy Prism library (~500KB) only when needed.
+ * This significantly reduces the initial bundle size.
+ */
+
+'use client';
+
+import React, { lazy, Suspense } from 'react';
+import type { Language } from 'prism-react-renderer';
+
+import { LoadingFallback } from '@djangocfg/widget-kit/lazy';
+
+// Lazy load the client component
+const PrettyCodeClient = lazy(() => import('./PrettyCode.client'));
+
+// Shared compact placeholder (16px muted spinner), inside the code-surface
+// border so nothing shifts when PrettyCode mounts. Same look as LazyPrettyCode
+// (lazy.tsx) and the JSON viewer.
+const CodeFallback = () => (
+  <LoadingFallback
+    minHeight={64}
+    text="Loading code…"
+    className="rounded-sm border border-border bg-muted dark:bg-code"
+  />
+);
+
+export interface PrettyCodeProps {
+  data: string | object;
+  language: Language;
+  className?: string;
+  mode?: 'dark' | 'light';
+  inline?: boolean;
+  customBg?: string;
+  isCompact?: boolean;
+  /** Block scroll capture until user clicks (default: true) */
+  scrollIsolation?: boolean;
+  /**
+   * Line count above which the block starts scrolling instead of growing.
+   * ``undefined`` (default) = no cap, block grows to fit. Set e.g. ``50``
+   * to inline short snippets and cap long ones.
+   */
+  maxLines?: number;
+  /** When set, a header expand (⤢) button appears while the code is
+   *  height-capped (exceeds `maxLines`). Lets a host open it full-screen. */
+  onExpand?: () => void;
+  /**
+   * Visual variant:
+   *   - ``"card"`` (default) — full chrome: border, background, hover
+   *     toolbar (Copy + language tag), optional internal scroll. Suits
+   *     a standalone code block in documentation prose where the block
+   *     is its own surface.
+   *   - ``"plain"`` — chrome-less: no border, no background, no toolbar,
+   *     no internal scroll. Grows to fit its content. Use when
+   *     embedding inside another scroll container (e.g. the Response
+   *     panel) — avoids double-scroll surfaces and lets the parent
+   *     manage copy/language affordances.
+   */
+  variant?: 'card' | 'plain';
+}
+
+const PrettyCode: React.FC<PrettyCodeProps> = (props) => {
+  return (
+    <Suspense fallback={<CodeFallback />}>
+      <PrettyCodeClient {...props} />
+    </Suspense>
+  );
+};
+
+export default PrettyCode;
+export type { Language };

package/src/pretty-code/lazy.tsx

@@ -0,0 +1,69 @@
+'use client';
+
+/**
+ * Lazy-loaded PrettyCode Component
+ *
+ * Heavy Prism library (~500KB) is loaded only when component is rendered.
+ * Use this for automatic code-splitting with Suspense fallback.
+ *
+ * For direct imports without lazy loading, use:
+ * import PrettyCode from '@djangocfg/widget-code/pretty-code'
+ */
+
+import { createLazyComponent, LoadingFallback } from '@djangocfg/widget-kit/lazy';
+import type { Language } from 'prism-react-renderer';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface PrettyCodeProps {
+  data: string | object;
+  language: Language;
+  className?: string;
+  mode?: 'dark' | 'light';
+  inline?: boolean;
+  customBg?: string;
+  isCompact?: boolean;
+  scrollIsolation?: boolean;
+  maxLines?: number;
+  /** Header expand (⤢) callback, shown while the code is height-capped. */
+  onExpand?: () => void;
+  /** ``'card'`` (default) ships the full chrome. ``'plain'`` is
+   *  chrome-less — for embedding inside another scroll container. */
+  variant?: 'card' | 'plain';
+}
+
+export type { Language };
+
+// ============================================================================
+// Lazy Component
+// ============================================================================
+
+/**
+ * LazyPrettyCode - Lazy-loaded code syntax highlighter
+ *
+ * Automatically shows loading state while Prism loads (~500KB). Uses the shared
+ * compact `LoadingFallback` (16px muted spinner) so the code viewer and the JSON
+ * viewer show the SAME quiet placeholder while their chunks load — kept inside a
+ * subtle code-surface border so nothing shifts when PrettyCode mounts.
+ */
+export const LazyPrettyCode = createLazyComponent<PrettyCodeProps>(
+  () => import('./PrettyCode.client'),
+  {
+    displayName: 'LazyPrettyCode',
+    fallback: (
+      <LoadingFallback
+        minHeight={64}
+        text="Loading code…"
+        className="rounded-sm border border-border bg-muted dark:bg-code"
+      />
+    ),
+  }
+);
+
+// `PrettyCode` is the historical named export — same component as
+// `LazyPrettyCode`, kept for backwards compatibility with callers that
+// imported it from the old root barrel.
+export { LazyPrettyCode as PrettyCode };
+export { default } from './index';

package/src/pretty-code/pretty-code.stories.tsx

@@ -0,0 +1,353 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { LazyPrettyCode as PrettyCode } from './lazy';
+
+// ─── Samples ──────────────────────────────────────────────────────────────────
+
+const TS_SAMPLE = `import { useCallback, useEffect, useRef, useState } from 'react';
+
+export type Status = 'idle' | 'loading' | 'success' | 'error';
+
+export interface PaginationParams {
+  page: number;
+  pageSize: number;
+  sortBy?: string;
+  sortOrder?: 'asc' | 'desc';
+}
+
+export function useVehicles(initialParams?: Partial<PaginationParams>) {
+  const [status, setStatus] = useState<Status>('idle');
+  const [data, setData] = useState<unknown[]>([]);
+  const abortRef = useRef<AbortController | null>(null);
+
+  const fetch = useCallback(async (p: PaginationParams) => {
+    abortRef.current?.abort();
+    abortRef.current = new AbortController();
+    setStatus('loading');
+    const res = await window.fetch(\`/api/vehicles?page=\${p.page}\`, {
+      signal: abortRef.current.signal,
+    });
+    const json = await res.json();
+    setData(json.data);
+    setStatus('success');
+  }, []);
+
+  useEffect(() => {
+    fetch(initialParams as PaginationParams);
+    return () => abortRef.current?.abort();
+  }, []);
+
+  return { status, data };
+}`;
+
+const JSON_SAMPLE = {
+  framework: 'next',
+  version: '16.2.2',
+  features: ['app-router', 'rsc', 'turbopack'],
+  flags: { strictMode: true, experimentalRSC: true },
+  routes: [
+    { path: '/', component: 'HomePage' },
+    { path: '/about', component: 'AboutPage' },
+  ],
+};
+
+const PYTHON_SAMPLE = `from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass
+from datetime import datetime
+from enum import StrEnum
+
+import httpx
+from pydantic import BaseModel, Field, field_validator
+
+
+class FuelType(StrEnum):
+    GASOLINE = "gasoline"
+    DIESEL = "diesel"
+    ELECTRIC = "electric"
+
+
+class Vehicle(BaseModel):
+    id: str
+    make: str
+    model: str
+    year: int
+    fuel_type: FuelType
+    created_at: datetime = Field(default_factory=datetime.utcnow)
+
+    @field_validator("year")
+    @classmethod
+    def validate_year(cls, v: int) -> int:
+        if not (1900 <= v <= datetime.utcnow().year + 1):
+            raise ValueError(f"Invalid year: {v}")
+        return v
+
+
+@dataclass
+class VehicleRepository:
+    base_url: str
+
+    async def list(self, page: int = 1) -> list[Vehicle]:
+        async with httpx.AsyncClient(base_url=self.base_url) as client:
+            response = await client.get("/vehicles", params={"page": page})
+            response.raise_for_status()
+            return [Vehicle.model_validate(v) for v in response.json()["data"]]`;
+
+const BASH_SAMPLE = `#!/usr/bin/env bash
+set -euo pipefail
+
+# Deploy script for production
+ENV="\${1:-staging}"
+TAG="\${2:-latest}"
+
+echo "Deploying to \$ENV with tag \$TAG"
+
+docker build -t myapp:\$TAG .
+docker push registry.example.com/myapp:\$TAG
+
+kubectl set image deployment/myapp app=registry.example.com/myapp:\$TAG
+kubectl rollout status deployment/myapp --timeout=2m
+
+echo "Done."`;
+
+const SQL_SAMPLE = `-- Top selling vehicles in the last 30 days
+WITH recent_sales AS (
+  SELECT
+    v.id,
+    v.make,
+    v.model,
+    COUNT(s.id) AS sales_count,
+    SUM(s.amount) AS revenue
+  FROM vehicles v
+  INNER JOIN sales s ON s.vehicle_id = v.id
+  WHERE s.created_at >= NOW() - INTERVAL '30 days'
+  GROUP BY v.id, v.make, v.model
+)
+SELECT *
+FROM recent_sales
+WHERE sales_count > 5
+ORDER BY revenue DESC
+LIMIT 20;`;
+
+const YAML_SAMPLE = `version: '3.9'
+
+services:
+  api:
+    image: registry.example.com/myapp:latest
+    environment:
+      DATABASE_URL: postgres://db/app
+      REDIS_URL: redis://cache:6379
+    depends_on:
+      - db
+      - cache
+    ports:
+      - "8000:8000"
+
+  db:
+    image: postgres:16-alpine
+    volumes:
+      - db_data:/var/lib/postgresql/data
+    environment:
+      POSTGRES_DB: app
+      POSTGRES_PASSWORD: secret
+
+  cache:
+    image: redis:7-alpine
+
+volumes:
+  db_data:`;
+
+const LONG_SAMPLE = Array.from(
+  { length: 60 },
+  (_, i) => `const value_${i} = ${i * 3}; // computed entry ${i + 1}`,
+).join('\n');
+
+// ─── Meta ─────────────────────────────────────────────────────────────────────
+
+const meta = {
+  title: 'Widgets/Code/PrettyCode',
+  component: PrettyCode,
+  tags: ['autodocs'],
+  argTypes: {
+    data: { control: 'text', table: { category: 'Content' } },
+    language: {
+      control: 'select',
+      options: [
+        'tsx',
+        'ts',
+        'js',
+        'jsx',
+        'json',
+        'python',
+        'bash',
+        'sql',
+        'yaml',
+        'css',
+        'html',
+        'go',
+        'rust',
+        'markdown',
+      ],
+      table: { category: 'Content' },
+    },
+    mode: {
+      control: 'inline-radio',
+      options: ['dark', 'light'],
+      table: { category: 'Appearance' },
+    },
+    variant: {
+      control: 'inline-radio',
+      options: ['card', 'plain'],
+      table: { category: 'Appearance' },
+    },
+    inline: { control: 'boolean', table: { category: 'Appearance' } },
+    isCompact: { control: 'boolean', table: { category: 'Appearance' } },
+    customBg: { control: 'text', table: { category: 'Appearance' } },
+    scrollIsolation: { control: 'boolean', table: { category: 'Behaviour' } },
+    maxLines: { control: { type: 'number', min: 0, step: 1 }, table: { category: 'Behaviour' } },
+  },
+} satisfies Meta<typeof PrettyCode>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+const Frame = ({ children }: { children: React.ReactNode }) => (
+  <div className="w-[720px]">{children}</div>
+);
+
+// ─── Playground ───────────────────────────────────────────────────────────────
+
+export const Playground: Story = {
+  args: {
+    data: TS_SAMPLE,
+    language: 'tsx',
+    mode: 'dark',
+    variant: 'card',
+    inline: false,
+    isCompact: false,
+    scrollIsolation: true,
+  },
+  render: (args) => (
+    <Frame>
+      <PrettyCode {...args} />
+    </Frame>
+  ),
+};
+
+// ─── Curated presets ──────────────────────────────────────────────────────────
+
+export const TypeScript: Story = {
+  args: { data: TS_SAMPLE, language: 'tsx' },
+  render: (args) => (
+    <Frame>
+      <PrettyCode {...args} />
+    </Frame>
+  ),
+};
+
+export const Json: Story = {
+  args: { data: JSON_SAMPLE, language: 'json' },
+  render: (args) => (
+    <Frame>
+      <PrettyCode {...args} />
+    </Frame>
+  ),
+};
+
+export const Python: Story = {
+  args: { data: PYTHON_SAMPLE, language: 'python' },
+  render: (args) => (
+    <Frame>
+      <PrettyCode {...args} />
+    </Frame>
+  ),
+};
+
+export const Bash: Story = {
+  args: { data: BASH_SAMPLE, language: 'bash' },
+  render: (args) => (
+    <Frame>
+      <PrettyCode {...args} />
+    </Frame>
+  ),
+};
+
+export const Sql: Story = {
+  args: { data: SQL_SAMPLE, language: 'sql' },
+  render: (args) => (
+    <Frame>
+      <PrettyCode {...args} />
+    </Frame>
+  ),
+};
+
+export const Yaml: Story = {
+  args: { data: YAML_SAMPLE, language: 'yaml' },
+  render: (args) => (
+    <Frame>
+      <PrettyCode {...args} />
+    </Frame>
+  ),
+};
+
+export const LongFileWithScroll: Story = {
+  args: {
+    data: LONG_SAMPLE,
+    language: 'ts',
+    maxLines: 20,
+  },
+  render: (args) => (
+    <Frame>
+      <PrettyCode {...args} />
+    </Frame>
+  ),
+};
+
+export const Inline: Story = {
+  args: {
+    data: `const status: 'ok' | 'err' = 'ok';`,
+    language: 'ts',
+    inline: true,
+  },
+  render: (args) => (
+    <div className="text-sm">
+      The variable <PrettyCode {...args} /> represents the result state.
+    </div>
+  ),
+};
+
+export const Compact: Story = {
+  args: {
+    data: `const port = 3000;`,
+    language: 'ts',
+    isCompact: true,
+  },
+  render: (args) => <PrettyCode {...args} />,
+};
+
+export const LightMode: Story = {
+  args: {
+    data: TS_SAMPLE,
+    language: 'tsx',
+    mode: 'light',
+  },
+  render: (args) => (
+    <Frame>
+      <PrettyCode {...args} />
+    </Frame>
+  ),
+};
+
+export const PlainVariant: Story = {
+  args: {
+    data: TS_SAMPLE,
+    language: 'tsx',
+    variant: 'plain',
+  },
+  render: (args) => (
+    <Frame>
+      <PrettyCode {...args} />
+    </Frame>
+  ),
+};

package/src/pretty-code/registerPrismLanguages.ts

@@ -0,0 +1,116 @@
+/**
+ * Register extra Prism language grammars onto the vendored Prism
+ * instance that ``prism-react-renderer`` ships.
+ *
+ *  Why this file exists:
+ *    ``prism-react-renderer@2.x`` bundles only a small set of core
+ *    languages (javascript, typescript, python, go, json, css,
+ *    markup, clike, …). Anything else — ``bash``, ``ruby``, ``java``,
+ *    ``php`` — isn't in the bundle, so passing ``language="bash"`` to
+ *    ``<Highlight>`` silently renders as plain text.
+ *
+ *  Canonical solution (per the official README):
+ *    - Grab the exported ``Prism`` instance.
+ *    - Hang it off ``globalThis`` so that ``prismjs`` language
+ *      components can find it when they self-register (they read
+ *      ``window.Prism`` / ``global.Prism`` at module-evaluation time).
+ *    - Load each grammar via dynamic ``import()`` — bare ``require``
+ *      doesn't work in ESM/Vite and static ``import 'prismjs/…'``
+ *      runs before we can hang Prism on the global.
+ *
+ *  Runs once on module load, with a guard so repeated imports in
+ *  different bundles are a no-op. Safe for SSR: the grammars don't
+ *  touch the DOM and the dynamic import is awaited asynchronously —
+ *  server renders just miss the extra grammars, client renders pick
+ *  them up after hydration which is when the <Highlight> components
+ *  actually render anyway.
+ */
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+import { useSyncExternalStore } from 'react';
+import { Prism } from 'prism-react-renderer';
+
+// Hang the vendored Prism on the global so ``prismjs`` language
+// components can find it when their self-registration runs.
+const globalScope: any = typeof globalThis !== 'undefined' ? globalThis : {};
+if (!globalScope.Prism) {
+    globalScope.Prism = Prism;
+}
+
+// Ready-state machinery: one-shot boolean + subscribers. When loading
+// finishes we flip ``ready`` and notify listeners so components that
+// rendered before the grammars loaded can re-render and pick them up.
+let ready = false;
+let loading: Promise<void> | null = null;
+const listeners = new Set<() => void>();
+
+function subscribe(cb: () => void): () => void {
+    listeners.add(cb);
+    return () => listeners.delete(cb);
+}
+
+function getSnapshot(): boolean {
+    return ready;
+}
+
+// Server snapshot — always ``true`` so SSR doesn't trip the
+// ``server ≠ client`` warning. The actual registration only runs on
+// the client; server renders fall back to the bundled Prism set,
+// which for the OpenAPI viewer means JS / Python / Go highlight
+// server-side and bash / java / ruby / php render plain until hydration.
+function getServerSnapshot(): boolean {
+    return true;
+}
+
+export async function ensurePrismLanguages(): Promise<void> {
+    if (ready) return;
+    if (loading) return loading;
+
+    loading = (async () => {
+        // Dynamic imports so these modules evaluate AFTER we've
+        // attached Prism to the global scope above.
+        //
+        // `as string` because the grammar files are untyped side-effect
+        // modules — `prismjs` ships no declarations for `components/*` and
+        // there is no `@types/prismjs` here. It widens the specifier, not a
+        // value, so nothing about the loaded module is being asserted.
+        //
+        // Load order matters: ``prism-php`` calls
+        // ``Prism.languages.markup.tokenizePlaceholders`` at module
+        // evaluation time, which is only defined after
+        // ``markup-templating`` loads — so that must come first.
+        // ``bash`` / ``java`` / ``ruby`` only depend on ``clike``
+        // which is already bundled in ``prism-react-renderer``.
+        await import('prismjs/components/prism-markup-templating' as string);
+        await Promise.all([
+            import('prismjs/components/prism-bash' as string),
+            import('prismjs/components/prism-java' as string),
+            import('prismjs/components/prism-ruby' as string),
+            import('prismjs/components/prism-php' as string),
+        ]);
+        ready = true;
+        listeners.forEach((cb) => cb());
+    })();
+
+    return loading;
+}
+
+/** Hook that triggers a re-render when the extra grammars finish
+ *  loading. Used by ``PrettyCode`` so the first render (which might
+ *  happen before loading completes) gets re-highlighted once the
+ *  grammars are available. */
+export function useEnsurePrismLanguages(): boolean {
+    const loaded = useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+    if (!loaded) {
+        // Kick off loading (idempotent — re-entry is cheap) so the
+        // next store update flips ``ready`` and we re-render.
+        void ensurePrismLanguages();
+    }
+    return loaded;
+}
+
+// Also kick off on module load so the grammars start loading as
+// early as possible — by the time the user clicks a code-sample tab
+// they've usually finished.
+void ensurePrismLanguages();