@djangocfg/ui-tools 2.1.289 → 2.1.291

package/src/tools/PrettyCode/PrettyCode.story.tsx

@@ -7,11 +7,11 @@ export default defineStory({
   description: 'Syntax highlighted code block with copy button.',
 });
 
+// ─── Samples ──────────────────────────────────────────────────────────────────
+
 const LONG_CODE_SAMPLES = {
   typescript: `import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 
-// ─── Types ────────────────────────────────────────────────────────────────────
-
 export type Status = 'idle' | 'loading' | 'success' | 'error';
 
 export interface PaginationParams {
@@ -21,70 +21,33 @@ export interface PaginationParams {
   sortOrder?: 'asc' | 'desc';
 }
 
-export interface ApiResponse<T> {
-  data: T[];
-  total: number;
-  page: number;
-  pageSize: number;
-  hasMore: boolean;
-}
-
-export interface Vehicle {
-  id: string;
-  make: string;
-  model: string;
-  year: number;
-  price: number;
-  mileage: number;
-  fuelType: 'gasoline' | 'diesel' | 'electric' | 'hybrid';
-  transmission: 'manual' | 'automatic';
-  color: string;
-  vin: string;
-  createdAt: Date;
-  updatedAt: Date;
-}
-
-// ─── Hook ─────────────────────────────────────────────────────────────────────
-
 export function useVehicles(initialParams?: Partial<PaginationParams>) {
   const [status, setStatus] = useState<Status>('idle');
-  const [data, setData] = useState<Vehicle[]>([]);
-  const [total, setTotal] = useState(0);
+  const [data, setData] = useState<unknown[]>([]);
   const [error, setError] = useState<Error | null>(null);
   const abortRef = useRef<AbortController | null>(null);
 
   const [params, setParams] = useState<PaginationParams>({
     page: 1,
     pageSize: 20,
-    sortBy: 'createdAt',
-    sortOrder: 'desc',
     ...initialParams,
   });
 
   const fetch = useCallback(async (p: PaginationParams) => {
     abortRef.current?.abort();
     abortRef.current = new AbortController();
-
     setStatus('loading');
-    setError(null);
-
     try {
       const query = new URLSearchParams({
         page: String(p.page),
         pageSize: String(p.pageSize),
-        ...(p.sortBy ? { sortBy: p.sortBy } : {}),
-        ...(p.sortOrder ? { sortOrder: p.sortOrder } : {}),
       });
-
       const res = await window.fetch(\`/api/vehicles?\${query}\`, {
         signal: abortRef.current.signal,
       });
-
-      if (!res.ok) throw new Error(\`HTTP \${res.status}: \${res.statusText}\`);
-
-      const json: ApiResponse<Vehicle> = await res.json();
+      if (!res.ok) throw new Error(\`HTTP \${res.status}\`);
+      const json = await res.json();
       setData(json.data);
-      setTotal(json.total);
       setStatus('success');
     } catch (err) {
       if ((err as Error).name === 'AbortError') return;
@@ -98,21 +61,7 @@ export function useVehicles(initialParams?: Partial<PaginationParams>) {
     return () => abortRef.current?.abort();
   }, [params, fetch]);
 
-  const hasMore = useMemo(
-    () => params.page * params.pageSize < total,
-    [params.page, params.pageSize, total],
-  );
-
-  const nextPage = useCallback(() =>
-    setParams(p => ({ ...p, page: p.page + 1 })), []);
-
-  const prevPage = useCallback(() =>
-    setParams(p => ({ ...p, page: Math.max(1, p.page - 1) })), []);
-
-  const sort = useCallback((sortBy: string, sortOrder: 'asc' | 'desc' = 'asc') =>
-    setParams(p => ({ ...p, sortBy, sortOrder, page: 1 })), []);
-
-  return { status, data, total, error, params, hasMore, nextPage, prevPage, sort };
+  return { status, data, error, params, setParams };
 }`,
 
   python: `from __future__ import annotations
@@ -122,42 +71,27 @@ import logging
 from dataclasses import dataclass, field
 from datetime import datetime
 from enum import StrEnum
-from typing import Any, AsyncIterator, Generic, TypeVar
-from uuid import UUID, uuid4
 
 import httpx
 from pydantic import BaseModel, ConfigDict, Field, field_validator
 
 logger = logging.getLogger(__name__)
 
-T = TypeVar("T")
-
-# ─── Enums ────────────────────────────────────────────────────────────────────
 
 class FuelType(StrEnum):
     GASOLINE = "gasoline"
     DIESEL = "diesel"
     ELECTRIC = "electric"
-    HYBRID = "hybrid"
-
-class Transmission(StrEnum):
-    MANUAL = "manual"
-    AUTOMATIC = "automatic"
 
-# ─── Models ───────────────────────────────────────────────────────────────────
 
 class Vehicle(BaseModel):
     model_config = ConfigDict(from_attributes=True)
 
-    id: UUID = Field(default_factory=uuid4)
+    id: str
     make: str
     model: str
     year: int
-    price: float
-    mileage: int
     fuel_type: FuelType
-    transmission: Transmission
-    vin: str
     created_at: datetime = Field(default_factory=datetime.utcnow)
 
     @field_validator("year")
@@ -167,93 +101,25 @@ class Vehicle(BaseModel):
             raise ValueError(f"Invalid year: {v}")
         return v
 
-    @field_validator("vin")
-    @classmethod
-    def validate_vin(cls, v: str) -> str:
-        if len(v) != 17:
-            raise ValueError("VIN must be exactly 17 characters")
-        return v.upper()
-
-class Page(BaseModel, Generic[T]):
-    data: list[T]
-    total: int
-    page: int
-    page_size: int
-
-    @property
-    def has_more(self) -> bool:
-        return self.page * self.page_size < self.total
-
-# ─── Repository ───────────────────────────────────────────────────────────────
 
 @dataclass
 class VehicleRepository:
     base_url: str
-    client: httpx.AsyncClient = field(init=False)
-
-    def __post_init__(self) -> None:
-        self.client = httpx.AsyncClient(
-            base_url=self.base_url,
-            timeout=httpx.Timeout(10.0),
-            headers={"Accept": "application/json"},
-        )
-
-    async def list(
-        self,
-        page: int = 1,
-        page_size: int = 20,
-        sort_by: str = "created_at",
-        sort_order: str = "desc",
-    ) -> Page[Vehicle]:
-        response = await self.client.get(
-            "/vehicles",
-            params={
-                "page": page,
-                "page_size": page_size,
-                "sort_by": sort_by,
-                "sort_order": sort_order,
-            },
-        )
-        response.raise_for_status()
-        payload = response.json()
-        return Page[Vehicle](
-            data=[Vehicle.model_validate(v) for v in payload["data"]],
-            total=payload["total"],
-            page=payload["page"],
-            page_size=payload["page_size"],
-        )
-
-    async def stream_all(self) -> AsyncIterator[Vehicle]:
-        page = 1
-        while True:
-            result = await self.list(page=page, page_size=100)
-            for vehicle in result.data:
-                yield vehicle
-            if not result.has_more:
-                break
-            page += 1
-
-    async def close(self) -> None:
-        await self.client.aclose()`,
-
-  javascript: `// ─── Event Bus ────────────────────────────────────────────────────────────────
-
-/**
- * Tiny type-safe event bus with wildcard support and once() semantics.
- * Zero dependencies, works in browser and Node.js.
- */
-
-/** @template {Record<string, unknown>} Events */
-class EventBus {
+
+    async def list(self, page: int = 1, page_size: int = 20) -> list[Vehicle]:
+        async with httpx.AsyncClient(base_url=self.base_url) as client:
+            response = await client.get(
+                "/vehicles",
+                params={"page": page, "page_size": page_size},
+            )
+            response.raise_for_status()
+            payload = response.json()
+            return [Vehicle.model_validate(v) for v in payload["data"]]`,
+
+  javascript: `class EventBus {
   #listeners = new Map();
   #wildcards = new Set();
 
-  /**
-   * Subscribe to an event.
-   * @param {string} event
-   * @param {Function} handler
-   * @returns {() => void} unsubscribe
-   */
   on(event, handler) {
     if (event === '*') {
       this.#wildcards.add(handler);
@@ -266,11 +132,6 @@ class EventBus {
     return () => this.#listeners.get(event)?.delete(handler);
   }
 
-  /**
-   * Subscribe once — auto-unsubscribes after first call.
-   * @param {string} event
-   * @param {Function} handler
-   */
   once(event, handler) {
     const unsub = this.on(event, (...args) => {
       unsub();
@@ -279,273 +140,165 @@ class EventBus {
     return unsub;
   }
 
-  /**
-   * Emit an event with payload.
-   * @param {string} event
-   * @param {unknown} payload
-   */
   emit(event, payload) {
     this.#listeners.get(event)?.forEach(h => h(payload));
     this.#wildcards.forEach(h => h(event, payload));
   }
-
-  /** Remove all listeners for an event, or all events if omitted. */
-  off(event) {
-    if (event) {
-      this.#listeners.delete(event);
-    } else {
-      this.#listeners.clear();
-      this.#wildcards.clear();
-    }
-  }
 }
 
-// ─── Usage ────────────────────────────────────────────────────────────────────
-
 const bus = new EventBus();
+bus.on('*', (event, payload) => console.debug(\`[bus] \${event}\`, payload));
+bus.emit('vehicle:created', { id: 'v_001', make: 'BMW' });`,
 
-// Wildcard — log everything
-bus.on('*', (event, payload) => {
-  console.debug(\`[bus] \${event}\`, payload);
-});
-
-// Subscribe
-const unsubscribe = bus.on('vehicle:created', ({ id, make, model }) => {
-  console.log(\`New vehicle: \${make} \${model} (\${id})\`);
-});
-
-// One-time subscription
-bus.once('vehicle:deleted', ({ id }) => {
-  console.warn(\`Vehicle \${id} deleted — cleaning up cache\`);
-});
-
-// Emit
-bus.emit('vehicle:created', { id: 'v_001', make: 'BMW', model: 'X5', year: 2023 });
-bus.emit('vehicle:updated', { id: 'v_001', price: 62000 });
-bus.emit('vehicle:deleted', { id: 'v_001' });
-
-// Unsubscribe
-unsubscribe();`,
-
-  css: `/* ─── Design Tokens ──────────────────────────────────────────────────────── */
-
-:root {
-  --radius-sm: 0.25rem;
+  css: `:root {
   --radius-md: 0.5rem;
-  --radius-lg: 0.75rem;
-  --radius-xl: 1rem;
-
   --shadow-sm: 0 1px 2px 0 rgb(0 0 0 / 0.05);
-  --shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1);
-  --shadow-lg: 0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1);
-
-  --transition-fast: 150ms cubic-bezier(0.4, 0, 0.2, 1);
   --transition-base: 200ms cubic-bezier(0.4, 0, 0.2, 1);
-  --transition-slow: 300ms cubic-bezier(0.4, 0, 0.2, 1);
 }
 
-/* ─── Card ───────────────────────────────────────────────────────────────── */
-
 .card {
-  position: relative;
-  display: flex;
-  flex-direction: column;
-  border-radius: var(--radius-lg);
+  border-radius: var(--radius-md);
   border: 1px solid hsl(var(--border));
   background: hsl(var(--card));
   box-shadow: var(--shadow-sm);
-  overflow: hidden;
-  transition: box-shadow var(--transition-base), transform var(--transition-base);
+  transition: box-shadow var(--transition-base);
 
   &:hover {
     box-shadow: var(--shadow-md);
     transform: translateY(-1px);
   }
-
-  &:focus-within {
-    outline: 2px solid hsl(var(--ring));
-    outline-offset: 2px;
-  }
-}
-
-.card-header {
-  display: flex;
-  align-items: center;
-  justify-content: space-between;
-  padding: 1rem 1.25rem 0.75rem;
-  border-bottom: 1px solid hsl(var(--border) / 0.5);
-}
-
-.card-title {
-  font-size: 0.9375rem;
-  font-weight: 600;
-  line-height: 1.4;
-  color: hsl(var(--foreground));
-  margin: 0;
-}
-
-.card-body {
-  flex: 1;
-  padding: 1rem 1.25rem;
-  overflow-y: auto;
-}
-
-.card-footer {
-  display: flex;
-  align-items: center;
-  gap: 0.5rem;
-  padding: 0.75rem 1.25rem;
-  border-top: 1px solid hsl(var(--border) / 0.5);
-  background: hsl(var(--muted) / 0.3);
-}
-
-/* ─── Variants ───────────────────────────────────────────────────────────── */
-
-.card--compact {
-  .card-header { padding: 0.625rem 1rem 0.5rem; }
-  .card-body   { padding: 0.625rem 1rem; }
-  .card-footer { padding: 0.5rem 1rem; }
-  .card-title  { font-size: 0.875rem; }
-}
-
-.card--ghost {
-  border-color: transparent;
-  background: transparent;
-  box-shadow: none;
-
-  &:hover {
-    background: hsl(var(--muted) / 0.5);
-    transform: none;
-    box-shadow: none;
-  }
 }
 
-/* ─── Skeleton loader ────────────────────────────────────────────────────── */
-
 @keyframes shimmer {
   from { background-position: -200% 0; }
   to   { background-position:  200% 0; }
 }
 
-.card--skeleton {
-  pointer-events: none;
-
-  .card-title,
-  .card-body > * {
-    border-radius: var(--radius-sm);
-    background: linear-gradient(
-      90deg,
-      hsl(var(--muted)) 25%,
-      hsl(var(--muted-foreground) / 0.1) 50%,
-      hsl(var(--muted)) 75%
-    );
-    background-size: 200% 100%;
-    animation: shimmer 1.5s infinite;
-    color: transparent;
-  }
+.card--skeleton .card-title {
+  background: linear-gradient(90deg, hsl(var(--muted)) 25%, hsl(var(--muted-foreground) / 0.1) 50%, hsl(var(--muted)) 75%);
+  background-size: 200% 100%;
+  animation: shimmer 1.5s infinite;
 }`,
-};
 
-const CODE_SAMPLES = {
-  javascript: LONG_CODE_SAMPLES.javascript,
-  typescript: LONG_CODE_SAMPLES.typescript,
-  python: LONG_CODE_SAMPLES.python,
-  css: LONG_CODE_SAMPLES.css,
+  html: `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <title>Sample</title>
+</head>
+<body>
+  <div id="root"></div>
+  <script type="module" src="/entry.tsx"></script>
+</body>
+</html>`,
 };
 
+// ─── Stories ──────────────────────────────────────────────────────────────────
+
+/** Interactive — language, variant, compact, scrollIsolation all toggleable.
+ *  Replaces the old per-language / per-mode / per-flag stories which were
+ *  just this component with different defaults. */
 export const Interactive = () => {
   const [language] = useSelect('language', {
-    options: ['javascript', 'typescript', 'python', 'css'] as const,
+    options: ['typescript', 'javascript', 'python', 'css', 'html'] as const,
     defaultValue: 'typescript',
     label: 'Language',
-    description: 'Programming language for syntax highlighting',
+  });
+
+  const [variant] = useSelect('variant', {
+    options: ['card', 'plain'] as const,
+    defaultValue: 'card',
+    label: 'Variant',
+    description: 'card = full chrome, plain = bare highlighted code',
   });
 
   const [isCompact] = useBoolean('isCompact', {
     defaultValue: false,
     label: 'Compact',
-    description: 'Use compact styling',
   });
 
-  // No mode prop — component follows playground theme via useResolvedTheme
+  const [scrollIsolation] = useBoolean('scrollIsolation', {
+    defaultValue: true,
+    label: 'Scroll isolation',
+    description: 'Require click before the block captures scroll (card only)',
+  });
+
   return (
     <PrettyCode
-      data={CODE_SAMPLES[language]}
+      data={LONG_CODE_SAMPLES[language]}
       language={language}
+      variant={variant}
       isCompact={isCompact}
+      scrollIsolation={scrollIsolation}
     />
   );
 };
 
-export const JavaScript = () => (
-  <PrettyCode data={CODE_SAMPLES.javascript} language="javascript" />
-);
-
-export const TypeScript = () => (
-  <PrettyCode data={CODE_SAMPLES.typescript} language="typescript" />
-);
-
-export const Python = () => (
-  <PrettyCode data={CODE_SAMPLES.python} language="python" />
-);
-
-export const CSS = () => (
-  <PrettyCode data={CODE_SAMPLES.css} language="css" />
-);
-
-export const LightMode = () => (
-  <PrettyCode data={CODE_SAMPLES.typescript} language="typescript" mode="light" />
-);
-
-export const Compact = () => (
-  <PrettyCode data={CODE_SAMPLES.javascript} language="javascript" isCompact />
+/** Variants — ``card`` vs ``plain`` side by side. The card has its own
+ *  border, hover toolbar, and can internally scroll when a ``maxLines``
+ *  cap is hit. The plain variant is chrome-less for embedding inside
+ *  an existing scroll container (e.g. a response panel), where the
+ *  parent surface owns chrome and scroll. */
+export const Variants = () => (
+  <div className="grid grid-cols-1 lg:grid-cols-2 gap-4 max-w-6xl">
+    <section className="space-y-2">
+      <h3 className="text-sm font-semibold">variant=&quot;card&quot; (default)</h3>
+      <p className="text-xs text-muted-foreground">
+        Border, background, hover toolbar with Copy + language tag.
+      </p>
+      <PrettyCode data={LONG_CODE_SAMPLES.typescript} language="typescript" variant="card" />
+    </section>
+    <section className="space-y-2">
+      <h3 className="text-sm font-semibold">variant=&quot;plain&quot;</h3>
+      <p className="text-xs text-muted-foreground">
+        Chrome-less. No border, no background, no toolbar. Flows into the
+        parent scroll container.
+      </p>
+      <PrettyCode data={LONG_CODE_SAMPLES.typescript} language="typescript" variant="plain" />
+    </section>
+  </div>
 );
 
+/** LongCode — stress test for multi-column layouts and long snippets. */
 export const LongCode = () => (
   <div className="flex flex-col gap-6 max-w-4xl">
     <div className="h-96">
-      <PrettyCode data={LONG_CODE_SAMPLES.typescript} language="typescript" />
+      <PrettyCode data={LONG_CODE_SAMPLES.typescript} language="typescript" maxLines={30} />
     </div>
     <div className="h-96">
-      <PrettyCode data={LONG_CODE_SAMPLES.python} language="python" />
+      <PrettyCode data={LONG_CODE_SAMPLES.python} language="python" maxLines={30} />
     </div>
     <div className="h-96">
-      <PrettyCode data={LONG_CODE_SAMPLES.javascript} language="javascript" />
-    </div>
-    <div className="h-96">
-      <PrettyCode data={LONG_CODE_SAMPLES.css} language="css" />
+      <PrettyCode data={LONG_CODE_SAMPLES.javascript} language="javascript" maxLines={30} />
     </div>
   </div>
 );
 
-/** Scroll isolation disabled — block scrolls freely without clicking first */
-export const ScrollIsolationOff = () => (
-  <div className="flex flex-col gap-6 max-w-4xl">
-    <p className="text-sm text-muted-foreground">
-      <strong>scrollIsolation=false</strong> — scroll works immediately without clicking.
-    </p>
-    <div className="h-96">
-      <PrettyCode
-        data={LONG_CODE_SAMPLES.typescript}
-        language="typescript"
-        scrollIsolation={false}
-      />
-    </div>
-  </div>
-);
-
-/** Scroll isolation enabled (default) — must click the block first to scroll inside */
-export const ScrollIsolationOn = () => (
-  <div className="flex flex-col gap-6 max-w-4xl">
-    <p className="text-sm text-muted-foreground">
-      <strong>scrollIsolation=true</strong> (default) — hover to see the hint, click to unlock scroll.
-    </p>
-    <div className="h-96">
-      <PrettyCode
-        data={LONG_CODE_SAMPLES.typescript}
-        language="typescript"
-        scrollIsolation
-      />
-    </div>
+/** ScrollIsolation — both states side-by-side so the difference is
+ *  obvious without toggling. The isolation flag matters most when the
+ *  block is embedded in a scrolling page: without it, wheel-scrolling
+ *  anywhere over the block "captures" the wheel and the page itself
+ *  stops scrolling — click-to-unlock avoids that surprise. */
+export const ScrollIsolation = () => (
+  <div className="flex flex-col gap-8 max-w-4xl">
+    <section className="space-y-2">
+      <h3 className="text-sm font-semibold">scrollIsolation=true (default)</h3>
+      <p className="text-xs text-muted-foreground">
+        Hover to see the hint; click to unlock wheel-scroll inside the block.
+      </p>
+      <div className="h-64">
+        <PrettyCode data={LONG_CODE_SAMPLES.typescript} language="typescript" maxLines={15} scrollIsolation />
+      </div>
+    </section>
+    <section className="space-y-2">
+      <h3 className="text-sm font-semibold">scrollIsolation=false</h3>
+      <p className="text-xs text-muted-foreground">
+        Wheel-scroll captured immediately — use when the block has no
+        surrounding page-level scroll to compete with.
+      </p>
+      <div className="h-64">
+        <PrettyCode data={LONG_CODE_SAMPLES.typescript} language="typescript" maxLines={15} scrollIsolation={false} />
+      </div>
+    </section>
   </div>
 );

package/src/tools/PrettyCode/index.tsx

@@ -41,6 +41,19 @@ export interface PrettyCodeProps {
    * to inline short snippets and cap long ones.
    */
   maxLines?: number;
+  /**
+   * 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) => {

package/src/tools/PrettyCode/lazy.tsx

@@ -25,6 +25,11 @@ export interface PrettyCodeProps {
   inline?: boolean;
   customBg?: string;
   isCompact?: boolean;
+  scrollIsolation?: boolean;
+  maxLines?: number;
+  /** ``'card'`` (default) ships the full chrome. ``'plain'`` is
+   *  chrome-less — for embedding inside another scroll container. */
+  variant?: 'card' | 'plain';
 }
 
 export type { Language };