@terrafirmagreg-team/mdx 0.0.0-stage → 1.2.0

package/package.json

@@ -1,6 +1,64 @@
 {
   "name": "@terrafirmagreg-team/mdx",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.2.0",
+  "type": "module",
+  "description": "MDX/markdown pipeline",
+  "license": "LGPL-3.0-only",
+  "exports": {
+    "./lib": "./src/lib/index.ts",
+    "./lib/*": [
+      "./src/lib/*.ts",
+      "./src/lib/*/index.ts"
+    ],
+    "./components/*": [
+      "./src/components/*.tsx",
+      "./src/components/*/index.tsx",
+      "./src/components/*/index.ts"
+    ],
+    "./types/*": "./src/types/*.ts",
+    "./types": "./src/types/index.ts"
+  },
+  "dependencies": {
+    "@fumadocs/story": "^1.5.3",
+    "@fumari/stf": "^1.1.2",
+    "@terrafirmagreg-team/translate": "1.2.0",
+    "@terrafirmagreg-team/ui": "1.2.0",
+    "@types/turndown": "^5.0.6",
+    "fumadocs-core": "16.17.8",
+    "fumadocs-docgen": "^3.2.0",
+    "fumadocs-twoslash": "^4.0.4",
+    "fumadocs-typescript": "5.6.0",
+    "lucide-react": "^0.577.0",
+    "rehype-katex": "^7.0.1",
+    "rehype-raw": "^7.0.0",
+    "remark-directive": "^4.0.0",
+    "remark-gfm": "^4.0.1",
+    "remark-math": "^6.0.0",
+    "remark-parse": "^11.0.0",
+    "turndown": "^7.2.5",
+    "turndown-plugin-gfm": "^1.0.2",
+    "unified": "^11.0.5",
+    "unist-util-visit": "^5.2.0"
+  },
+  "peerDependencies": {
+    "next": ">=15",
+    "react": ">=19"
+  },
+  "devDependencies": {
+    "@types/mdx": "^2.0.14",
+    "@types/node": "^26.6.5",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/TerraFirmaGreg-Team/Web-Foundation.git",
+    "directory": "packages/mdx"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src"
+  ]
 }

package/src/components/docs-image.tsx

@@ -0,0 +1,62 @@
+import { ImageZoom } from '@terrafirmagreg-team/ui/components/mdx/image-zoom';
+import { resolveSrc } from '../lib/pack-assets';
+import type { DocsImageProps } from '../types/mdx';
+
+export function DocsImage({
+  src,
+  pack,
+  mod,
+  path,
+  alt = '',
+  width,
+  height,
+  className,
+  caption,
+  defaultPack: pagePack,
+  ...rest
+}: DocsImageProps) {
+  const packHint = pack ?? pagePack;
+  const resolved = resolveSrc({ src, pack, mod, path }, packHint);
+  if (!resolved) {
+    return (
+      <p className="not-prose text-sm text-muted-foreground">
+        Missing image source (set <code>src</code> or <code>mod</code>+
+        <code>path</code>; pack defaults from the docs slug).
+      </p>
+    );
+  }
+
+  const w = Number(width) || undefined;
+  const h = Number(height) || undefined;
+
+  return (
+    <figure className="not-prose my-4 space-y-2">
+      <ImageZoom
+        src={resolved}
+        alt={alt}
+        width={w ?? 960}
+        height={h ?? 540}
+        className={className}
+        {...rest}
+      >
+        {w === undefined || h === undefined ? (
+          // eslint-disable-next-line @next/next/no-img-element
+          <img
+            src={resolved}
+            alt={alt}
+            width={w}
+            height={h}
+            className={className}
+            style={{ width: w ?? 'auto', height: h ?? 'auto' }}
+          />
+        ) : undefined}
+      </ImageZoom>
+      {caption ? (
+        <figcaption className="text-center text-sm text-muted-foreground">
+          {caption}
+        </figcaption>
+      ) : null}
+    </figure>
+  );
+}
+

package/src/components/mdx-components.tsx

@@ -0,0 +1,158 @@
+import {
+  Tab,
+  Tabs,
+  TabsContent,
+  TabsList,
+  TabsTrigger,
+} from '@terrafirmagreg-team/ui/components/mdx/tabs';
+import {
+  Accordion,
+  Accordions,
+} from '@terrafirmagreg-team/ui/components/mdx/accordion';
+import { Step, Steps } from '@terrafirmagreg-team/ui/components/mdx/steps';
+import {
+  File,
+  Folder,
+  Files,
+} from '@terrafirmagreg-team/ui/components/mdx/files';
+import { ImageZoom } from '@terrafirmagreg-team/ui/components/mdx/image-zoom';
+import { Banner } from '@terrafirmagreg-team/ui/components/mdx/banner';
+import { TypeTable } from '@terrafirmagreg-team/ui/components/mdx/type-table';
+import { Card, Cards } from '@terrafirmagreg-team/ui/components/mdx/card';
+import { Table } from '@terrafirmagreg-team/ui/components/mdx/table';
+import {
+  CalloutDescription,
+  CalloutTitle,
+} from '@terrafirmagreg-team/ui/components/mdx/callout';
+import {
+  CodeBlock,
+  CodeBlockTab,
+  CodeBlockTabs,
+  CodeBlockTabsList,
+  CodeBlockTabsTrigger,
+  Pre,
+} from '@terrafirmagreg-team/ui/components/mdx/codeblock';
+import { Heading } from '@terrafirmagreg-team/ui/components/blocks/page/heading';
+import * as Twoslash from 'fumadocs-twoslash/ui';
+import { Mermaid } from '@terrafirmagreg-team/ui/components/mdx/mermaid';
+import { Callout, CalloutContainer } from '@terrafirmagreg-team/ui/components/mdx/callout';
+import { Input, Output, Preview } from '@terrafirmagreg-team/ui/components/mdx/preview';
+import { DocsImage } from './docs-image';
+import { Multiblock } from '@terrafirmagreg-team/ui/components/mdx/multiblock';
+import { GradientText } from '@terrafirmagreg-team/ui/components/mdx/gradient-text';
+import { GlowHeader } from '@terrafirmagreg-team/ui/components/mdx/glow-header';
+import { Icon } from '@terrafirmagreg-team/ui/components/mdx/icon';
+import { LinkPreview } from '@terrafirmagreg-team/ui/components/blocks/link/link-preview';
+import type { MDXComponents } from 'mdx/types';
+import type { ComponentProps, HTMLAttributes } from 'react';
+
+const extras: MDXComponents = {};
+
+export function registerMdxComponents(map: MDXComponents): void {
+  Object.assign(extras, map);
+}
+
+export function getMDXComponents(components?: MDXComponents) {
+  return {
+    CodeBlockTab,
+    CodeBlockTabs,
+    CodeBlockTabsList,
+    CodeBlockTabsTrigger,
+    Tab,
+    Tabs,
+    TabsContent,
+    TabsList,
+    TabsTrigger,
+    ...Twoslash,
+    Accordion,
+    Accordions,
+    Step,
+    Steps,
+    File,
+    Folder,
+    Files,
+    Mermaid,
+    Banner,
+    TypeTable,
+    Card,
+    Cards,
+    Callout,
+    CalloutContainer,
+    CalloutTitle,
+    CalloutDescription,
+    Preview,
+    Input,
+    Output,
+    DocsImage,
+    Multiblock,
+    GradientText,
+    GlowHeader,
+    Icon,
+    a: LinkPreview,
+    pre: (props: HTMLAttributes<HTMLPreElement>) => (
+      <CodeBlock {...props}>
+        <Pre>{props.children}</Pre>
+      </CodeBlock>
+    ),
+    h1: (props: HTMLAttributes<HTMLHeadingElement>) => (
+      <Heading as="h1" {...props} />
+    ),
+    h2: (props: HTMLAttributes<HTMLHeadingElement>) => (
+      <Heading as="h2" {...props} />
+    ),
+    h3: (props: HTMLAttributes<HTMLHeadingElement>) => (
+      <Heading as="h3" {...props} />
+    ),
+    h4: (props: HTMLAttributes<HTMLHeadingElement>) => (
+      <Heading as="h4" {...props} />
+    ),
+    h5: (props: HTMLAttributes<HTMLHeadingElement>) => (
+      <Heading as="h5" {...props} />
+    ),
+    h6: (props: HTMLAttributes<HTMLHeadingElement>) => (
+      <Heading as="h6" {...props} />
+    ),
+    table: Table,
+    img: (props: ComponentProps<'img'>) => {
+      const src =
+        typeof props.src === 'object' && props.src !== null
+          ? ((props.src as { src?: string }).src ?? '')
+          : props.src;
+      if (typeof src !== 'string' || /^https?:\/\//i.test(src)) {
+        // eslint-disable-next-line @next/next/no-img-element
+        return <img {...props} src={src} alt={props.alt ?? ''} />;
+      }
+      const width = Number(props.width) || undefined;
+      const height = Number(props.height) || undefined;
+      return (
+        <ImageZoom
+          src={src}
+          alt={props.alt ?? ''}
+          width={width ?? 960}
+          height={height ?? 540}
+          sizes={props.sizes as string | undefined}
+          className={props.className}
+        >
+          {width === undefined || height === undefined ? (
+            // eslint-disable-next-line @next/next/no-img-element
+            <img
+              src={src}
+              alt={props.alt ?? ''}
+              width={width}
+              height={height}
+              className={props.className}
+              style={{ width: width ?? 'auto', height: height ?? 'auto' }}
+            />
+          ) : undefined}
+        </ImageZoom>
+      );
+    },
+    ...extras,
+    ...components,
+  } as MDXComponents;
+}
+
+declare global {
+  type MDXProvidedComponents = ReturnType<typeof getMDXComponents>;
+}
+

package/src/components/story-fields.tsx

@@ -0,0 +1,318 @@
+'use client';
+
+import { useDataEngine, useFieldValue } from '@fumari/stf';
+import {
+  typeToString,
+  validate,
+  type TypeNode,
+} from '@fumadocs/story/type-tree';
+import { directiveMeta } from '../lib/story-remark';
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '@terrafirmagreg-team/ui/components/ui/select';
+import { cn } from '@terrafirmagreg-team/ui/lib/utils/cn';
+import { X } from 'lucide-react';
+import { useState } from 'react';
+
+function resolveNode(node: TypeNode, value: unknown): TypeNode {
+  if (node.type === 'intersection') return resolveNode(node.intersection, value);
+  if (node.type !== 'union') return node;
+  return resolveNode(
+    node.types.find((item) => validate(item, value)) ?? node.types[0],
+    value,
+  );
+}
+
+function selectMembers(
+  node: TypeNode,
+): { label: string; value: unknown }[] | undefined {
+  if (node.type === 'enum') return node.members;
+  if (
+    node.type === 'union' &&
+    node.types.every((t) => t.type === 'literal')
+  ) {
+    return node.types.map((t) => ({
+      label: String(t.type === 'literal' ? t.value : ''),
+      value: t.type === 'literal' ? t.value : undefined,
+    }));
+  }
+  return undefined;
+}
+
+const inputClass =
+  'min-w-0 flex-1 bg-transparent px-3 text-fd-foreground outline-none placeholder:text-fd-muted-foreground/70 focus-visible:ring-1 focus-visible:ring-inset focus-visible:ring-fd-primary';
+
+function StringEditor({
+  name,
+  value,
+  setValue,
+  multiline,
+}: {
+  name: string;
+  value: unknown;
+  setValue: (v: unknown) => void;
+  multiline?: boolean;
+}) {
+  if (multiline) {
+    const lineCount =
+      typeof value === 'string' ? value.split('\n').length : 0;
+    return (
+      <textarea
+        aria-label={name}
+        rows={Math.min(12, Math.max(4, lineCount + 1))}
+        value={value == null ? '' : String(value)}
+        placeholder="string"
+        onChange={(e) => setValue(e.target.value)}
+        className={cn(inputClass, 'min-h-12 resize-y py-2 font-mono text-xs')}
+      />
+    );
+  }
+  return (
+    <input
+      aria-label={name}
+      value={value == null ? '' : String(value)}
+      placeholder="string"
+      onChange={(e) => setValue(e.target.value)}
+      className={inputClass}
+    />
+  );
+}
+
+function NumberEditor({
+  name,
+  value,
+  setValue,
+}: {
+  name: string;
+  value: unknown;
+  setValue: (v: unknown) => void;
+}) {
+  return (
+    <input
+      aria-label={name}
+      type="number"
+      value={value == null ? '' : String(value)}
+      placeholder="number"
+      onChange={(e) =>
+        setValue(e.target.value === '' ? undefined : Number(e.target.value))
+      }
+      className={inputClass}
+    />
+  );
+}
+
+function BooleanEditor({
+  name,
+  value,
+  setValue,
+}: {
+  name: string;
+  value: unknown;
+  setValue: (v: unknown) => void;
+}) {
+  return (
+    <input
+      aria-label={name}
+      type="checkbox"
+      checked={value === true}
+      onChange={(e) => setValue(e.target.checked)}
+      className="mx-3 size-3.5 shrink-0 accent-fd-primary"
+    />
+  );
+}
+
+function SelectEditor({
+  name,
+  value,
+  setValue,
+  members,
+}: {
+  name: string;
+  value: unknown;
+  setValue: (v: unknown) => void;
+  members: { label: string; value: unknown }[];
+}) {
+  const index = members.findIndex((m) => Object.is(m.value, value));
+  return (
+    <Select
+      value={index < 0 ? '' : String(index)}
+      onValueChange={(v) => {
+        const next = members[Number(v)];
+        if (next) setValue(next.value);
+      }}
+    >
+      <SelectTrigger
+        aria-label={name}
+        className="h-8 flex-1 gap-1 border-0 bg-transparent px-3 text-xs shadow-none focus:ring-0 focus-visible:ring-1"
+      >
+        <SelectValue placeholder="select">
+          {(v: unknown) =>
+            typeof v === 'string' && v !== ''
+              ? members[Number(v)]?.label
+              : null
+          }
+        </SelectValue>
+      </SelectTrigger>
+      <SelectContent>
+        {members.map((m, i) => (
+          <SelectItem key={i} value={String(i)} className="text-xs">
+            {m.label}
+          </SelectItem>
+        ))}
+      </SelectContent>
+    </Select>
+  );
+}
+
+function JsonEditor({
+  name,
+  value,
+  setValue,
+}: {
+  name: string;
+  value: unknown;
+  setValue: (v: unknown) => void;
+}) {
+  const [text, setText] = useState(() =>
+    value === undefined ? '' : JSON.stringify(value),
+  );
+  const [invalid, setInvalid] = useState(false);
+  const [prevValue, setPrevValue] = useState(value);
+  if (prevValue !== value) {
+    setPrevValue(value);
+    setText(value === undefined ? '' : JSON.stringify(value));
+    setInvalid(false);
+  }
+  return (
+    <textarea
+      aria-label={name}
+      rows={2}
+      value={text}
+      placeholder="JSON"
+      onChange={(e) => {
+        const next = e.target.value;
+        setText(next);
+        if (next.trim() === '') {
+          setValue(undefined);
+          setInvalid(false);
+          return;
+        }
+        try {
+          setValue(JSON.parse(next));
+          setInvalid(false);
+        } catch {
+          setInvalid(true);
+        }
+      }}
+      className={cn(
+        inputClass,
+        'min-h-10 resize-y py-2 font-mono text-xs',
+        invalid && 'text-fd-error',
+      )}
+    />
+  );
+}
+
+function Field({
+  name,
+  node,
+  required,
+  multiline,
+  description,
+}: {
+  name: string;
+  node: TypeNode;
+  required?: boolean;
+  multiline?: boolean;
+  description?: string;
+}) {
+  const engine = useDataEngine();
+  const [value, setValue] = useFieldValue([name]);
+  const resolved = resolveNode(node, value);
+  const members = selectMembers(resolved);
+
+  let editor: React.ReactNode;
+  if (members) {
+    editor = (
+      <SelectEditor
+        name={name}
+        value={value}
+        setValue={setValue}
+        members={members}
+      />
+    );
+  } else if (resolved.type === 'boolean') {
+    editor = <BooleanEditor name={name} value={value} setValue={setValue} />;
+  } else if (resolved.type === 'number' || resolved.type === 'bigint') {
+    editor = <NumberEditor name={name} value={value} setValue={setValue} />;
+  } else if (resolved.type === 'string' || resolved.type === 'literal') {
+    editor = (
+      <StringEditor
+        name={name}
+        value={value}
+        setValue={setValue}
+        multiline={multiline}
+      />
+    );
+  } else {
+    editor = <JsonEditor name={name} value={value} setValue={setValue} />;
+  }
+
+  return (
+    <div className="flex min-h-10 items-center border-b last:border-0">
+      <span
+        className="flex w-28 shrink-0 items-center gap-1 px-3 font-mono text-[0.8125rem] text-fd-muted-foreground"
+        title={description}
+      >
+        <span className="truncate">{name}</span>
+        {!required && <span className="text-fd-muted-foreground/60">?</span>}
+      </span>
+      {editor}
+      <span className="hidden w-24 shrink-0 truncate px-2 font-mono text-xs text-fd-muted-foreground/70 @3xl:block">
+        {typeToString(resolved)}
+      </span>
+      {!required && (
+        <button
+          type="button"
+          aria-label={`Unset ${name}`}
+          onClick={() => engine.delete([name])}
+          className="me-2 flex size-6 shrink-0 items-center justify-center rounded-md text-fd-muted-foreground hover:bg-fd-accent hover:text-fd-foreground"
+        >
+          <X className="size-3" />
+        </button>
+      )}
+    </div>
+  );
+}
+
+export function StoryFields({
+  node,
+  storyKey,
+}: {
+  node: TypeNode;
+  storyKey: string;
+}) {
+  const meta = directiveMeta(storyKey);
+  if (node.type !== 'object') return null;
+  const multiline = new Set(meta?.multiline ?? []);
+  const descriptions = meta?.descriptions ?? {};
+  return (
+    <div className="text-[0.8125rem]">
+      {node.properties.map((prop) => (
+        <Field
+          key={prop.name}
+          name={prop.name}
+          node={prop.type}
+          required={prop.required}
+          multiline={multiline.has(prop.name)}
+          description={descriptions[prop.name]}
+        />
+      ))}
+    </div>
+  );
+}
+