@fragments-sdk/viewer 0.2.1

package/src/components/FragmentEditor.tsx

@@ -0,0 +1,525 @@
+import { useState, useCallback } from "react";
+import { useForm, useFieldArray, Controller } from "react-hook-form";
+import type { Fragment, FragmentUsage, FragmentMeta } from '@fragments-sdk/core';
+import { Box, Text, Button, Stack } from "@fragments-sdk/ui";
+import { ChevronDownIcon } from "./Icons.js";
+
+interface FragmentEditorProps {
+  /** Component name */
+  componentName: string;
+  /** Initial fragment data (if exists) */
+  fragment?: Fragment;
+  /** Called when the user saves changes */
+  onSave: (fragment: Fragment) => Promise<void>;
+  /** Whether save is in progress */
+  saving?: boolean;
+}
+
+interface FormData {
+  name: string;
+  description: string;
+  usage: {
+    when: string[];
+    doNot: Array<{ text: string; instead?: string }>;
+  };
+  accessibility: {
+    role: string;
+    requirements: string[];
+  };
+  related: {
+    similar: string[];
+    composedWith: string[];
+    usedIn: string[];
+  };
+  meta: {
+    owner: string;
+    status: "draft" | "experimental" | "beta" | "stable" | "deprecated";
+    since: string;
+    tags: string[];
+  };
+}
+
+const inputStyle: React.CSSProperties = {
+  width: '100%',
+  padding: '6px 12px',
+  fontSize: '14px',
+  background: 'var(--bg-elevated)',
+  border: '1px solid var(--border)',
+  borderRadius: '8px',
+  outline: 'none',
+  color: 'var(--text-primary)',
+  boxSizing: 'border-box',
+};
+
+export function FragmentEditor({
+  componentName,
+  fragment,
+  onSave,
+  saving = false,
+}: FragmentEditorProps) {
+  const [expandedSections, setExpandedSections] = useState<Set<string>>(
+    new Set(["usage", "meta"])
+  );
+
+  const toggleSection = (section: string) => {
+    setExpandedSections((prev) => {
+      const next = new Set(prev);
+      if (next.has(section)) {
+        next.delete(section);
+      } else {
+        next.add(section);
+      }
+      return next;
+    });
+  };
+
+  const defaultValues: FormData = {
+    name: fragment?.name || componentName,
+    description: fragment?.description || "",
+    usage: {
+      when: fragment?.usage?.when || [],
+      doNot:
+        fragment?.usage?.doNot?.map((item) =>
+          typeof item === "string" ? { text: item } : item
+        ) || [],
+    },
+    accessibility: {
+      role: fragment?.accessibility?.role || "",
+      requirements: fragment?.accessibility?.requirements || [],
+    },
+    related: {
+      similar: fragment?.related?.similar || [],
+      composedWith: fragment?.related?.composedWith || [],
+      usedIn: fragment?.related?.usedIn || [],
+    },
+    meta: {
+      owner: fragment?.meta?.owner || "",
+      status: fragment?.meta?.status || "stable",
+      since: fragment?.meta?.since || "",
+      tags: fragment?.meta?.tags || [],
+    },
+  };
+
+  const {
+    register,
+    control,
+    handleSubmit,
+    formState: { isDirty },
+  } = useForm<FormData>({ defaultValues });
+
+  const {
+    fields: whenFields,
+    append: appendWhen,
+    remove: removeWhen,
+  } = useFieldArray({ control, name: "usage.when" as const });
+
+  const {
+    fields: doNotFields,
+    append: appendDoNot,
+    remove: removeDoNot,
+  } = useFieldArray({ control, name: "usage.doNot" });
+
+  const {
+    fields: requirementsFields,
+    append: appendRequirement,
+    remove: removeRequirement,
+  } = useFieldArray({ control, name: "accessibility.requirements" as const });
+
+  const onSubmit = useCallback(
+    async (data: FormData) => {
+      const fragment: Fragment = {
+        $schema: "https://fragments.dev/schema/v1.json",
+        name: data.name,
+        description: data.description || undefined,
+        usage: {
+          when: data.usage.when.filter(Boolean),
+          doNot: data.usage.doNot.filter((d) => d.text),
+        },
+        accessibility:
+          data.accessibility.role || data.accessibility.requirements.length > 0
+            ? {
+                role: data.accessibility.role || undefined,
+                requirements: data.accessibility.requirements.filter(Boolean),
+              }
+            : undefined,
+        related:
+          data.related.similar.length > 0 ||
+          data.related.composedWith.length > 0 ||
+          data.related.usedIn.length > 0
+            ? {
+                similar: data.related.similar.filter(Boolean),
+                composedWith: data.related.composedWith.filter(Boolean),
+                usedIn: data.related.usedIn.filter(Boolean),
+              }
+            : undefined,
+        meta: {
+          status: data.meta.status,
+          owner: data.meta.owner || undefined,
+          since: data.meta.since || undefined,
+          tags: data.meta.tags.filter(Boolean),
+        },
+      };
+
+      await onSave(fragment);
+    },
+    [onSave]
+  );
+
+  return (
+    <form
+      onSubmit={handleSubmit(onSubmit)}
+      style={{ height: '100%', display: 'flex', flexDirection: 'column', background: 'var(--bg-primary)' }}
+    >
+      {/* Header */}
+      <Box paddingX="md" paddingY="sm" borderBottom background="secondary">
+        <Text as="h3" size="sm" weight="semibold" style={{ margin: 0 }}>Fragment Editor</Text>
+        <Text size="xs" color="secondary" style={{ marginTop: '2px' }}>
+          Enrich {componentName} with metadata
+        </Text>
+      </Box>
+
+      {/* Scrollable content */}
+      <Box overflow="auto" style={{ flex: 1 }}>
+        {/* Basic Info */}
+        <Box padding="md" borderBottom>
+          <Text as="label" size="xs" weight="medium" color="secondary" style={{ display: 'block', marginBottom: '6px' }}>
+            Description
+          </Text>
+          <textarea
+            {...register("description")}
+            rows={3}
+            style={{
+              ...inputStyle,
+              resize: 'none',
+            }}
+            placeholder="Brief description of the component's purpose..."
+          />
+        </Box>
+
+        {/* Usage Section */}
+        <Section
+          title="Usage Guidelines"
+          expanded={expandedSections.has("usage")}
+          onToggle={() => toggleSection("usage")}
+        >
+          {/* When to Use */}
+          <div style={{ marginBottom: '16px' }}>
+            <Text as="label" size="xs" weight="medium" color="secondary" style={{ display: 'block', marginBottom: '8px' }}>
+              When to Use
+            </Text>
+            <Stack gap="sm">
+              {whenFields.map((field, index) => (
+                <Stack key={field.id} direction="row" gap="sm">
+                  <input
+                    {...register(`usage.when.${index}` as const)}
+                    style={{ ...inputStyle, flex: 1 }}
+                    placeholder="Scenario..."
+                  />
+                  <Button
+                    type="button"
+                    variant="ghost"
+                    size="sm"
+                    onClick={() => removeWhen(index)}
+                  >
+                    &times;
+                  </Button>
+                </Stack>
+              ))}
+              <Button
+                type="button"
+                variant="ghost"
+                size="sm"
+                onClick={() => appendWhen("")}
+                style={{ padding: 0, alignSelf: 'flex-start' }}
+              >
+                + Add scenario
+              </Button>
+            </Stack>
+          </div>
+
+          {/* Do Not */}
+          <div>
+            <Text as="label" size="xs" weight="medium" color="secondary" style={{ display: 'block', marginBottom: '8px' }}>
+              Do Not
+            </Text>
+            <Stack gap="sm">
+              {doNotFields.map((field, index) => (
+                <Stack key={field.id} direction="row" gap="sm">
+                  <input
+                    {...register(`usage.doNot.${index}.text` as const)}
+                    style={{ ...inputStyle, flex: 1 }}
+                    placeholder="What not to do..."
+                  />
+                  <input
+                    {...register(`usage.doNot.${index}.instead` as const)}
+                    style={{ ...inputStyle, width: '128px' }}
+                    placeholder="Instead..."
+                  />
+                  <Button
+                    type="button"
+                    variant="ghost"
+                    size="sm"
+                    onClick={() => removeDoNot(index)}
+                  >
+                    &times;
+                  </Button>
+                </Stack>
+              ))}
+              <Button
+                type="button"
+                variant="ghost"
+                size="sm"
+                onClick={() => appendDoNot({ text: "", instead: "" })}
+                style={{ padding: 0, alignSelf: 'flex-start' }}
+              >
+                + Add anti-pattern
+              </Button>
+            </Stack>
+          </div>
+        </Section>
+
+        {/* Accessibility Section */}
+        <Section
+          title="Accessibility"
+          expanded={expandedSections.has("accessibility")}
+          onToggle={() => toggleSection("accessibility")}
+        >
+          <div style={{ marginBottom: '16px' }}>
+            <Text as="label" size="xs" weight="medium" color="secondary" style={{ display: 'block', marginBottom: '6px' }}>
+              ARIA Role
+            </Text>
+            <input
+              {...register("accessibility.role")}
+              style={inputStyle}
+              placeholder="button, dialog, etc."
+            />
+          </div>
+
+          <div>
+            <Text as="label" size="xs" weight="medium" color="secondary" style={{ display: 'block', marginBottom: '8px' }}>
+              Requirements
+            </Text>
+            <Stack gap="sm">
+              {requirementsFields.map((field, index) => (
+                <Stack key={field.id} direction="row" gap="sm">
+                  <input
+                    {...register(
+                      `accessibility.requirements.${index}` as const
+                    )}
+                    style={{ ...inputStyle, flex: 1 }}
+                    placeholder="Requirement..."
+                  />
+                  <Button
+                    type="button"
+                    variant="ghost"
+                    size="sm"
+                    onClick={() => removeRequirement(index)}
+                  >
+                    &times;
+                  </Button>
+                </Stack>
+              ))}
+              <Button
+                type="button"
+                variant="ghost"
+                size="sm"
+                onClick={() => appendRequirement("")}
+                style={{ padding: 0, alignSelf: 'flex-start' }}
+              >
+                + Add requirement
+              </Button>
+            </Stack>
+          </div>
+        </Section>
+
+        {/* Related Components Section */}
+        <Section
+          title="Related Components"
+          expanded={expandedSections.has("related")}
+          onToggle={() => toggleSection("related")}
+        >
+          <RelatedField
+            label="Similar"
+            description="Alternative components"
+            name="related.similar"
+            control={control}
+            register={register}
+          />
+          <RelatedField
+            label="Composed With"
+            description="Often used together"
+            name="related.composedWith"
+            control={control}
+            register={register}
+          />
+          <RelatedField
+            label="Used In"
+            description="Parent components"
+            name="related.usedIn"
+            control={control}
+            register={register}
+          />
+        </Section>
+
+        {/* Meta Section */}
+        <Section
+          title="Metadata"
+          expanded={expandedSections.has("meta")}
+          onToggle={() => toggleSection("meta")}
+        >
+          <div style={{ display: 'grid', gridTemplateColumns: '1fr 1fr', gap: '16px', marginBottom: '16px' }}>
+            <div>
+              <Text as="label" size="xs" weight="medium" color="secondary" style={{ display: 'block', marginBottom: '6px' }}>
+                Status
+              </Text>
+              <select
+                {...register("meta.status")}
+                style={inputStyle}
+              >
+                <option value="draft">Draft</option>
+                <option value="experimental">Experimental</option>
+                <option value="beta">Beta</option>
+                <option value="stable">Stable</option>
+                <option value="deprecated">Deprecated</option>
+              </select>
+            </div>
+            <div>
+              <Text as="label" size="xs" weight="medium" color="secondary" style={{ display: 'block', marginBottom: '6px' }}>
+                Since Version
+              </Text>
+              <input
+                {...register("meta.since")}
+                style={inputStyle}
+                placeholder="1.0.0"
+              />
+            </div>
+          </div>
+          <div style={{ marginBottom: '16px' }}>
+            <Text as="label" size="xs" weight="medium" color="secondary" style={{ display: 'block', marginBottom: '6px' }}>
+              Owner
+            </Text>
+            <input
+              {...register("meta.owner")}
+              style={inputStyle}
+              placeholder="@team-name or email"
+            />
+          </div>
+        </Section>
+      </Box>
+
+      {/* Footer with save button */}
+      <Box paddingX="md" paddingY="sm" borderTop background="secondary">
+        <Button
+          type="submit"
+          variant="primary"
+          fullWidth
+          disabled={!isDirty || saving}
+        >
+          {saving ? "Saving..." : "Save Fragment"}
+        </Button>
+      </Box>
+    </form>
+  );
+}
+
+interface SectionProps {
+  title: string;
+  expanded: boolean;
+  onToggle: () => void;
+  children: React.ReactNode;
+}
+
+function Section({ title, expanded, onToggle, children }: SectionProps) {
+  const [hovered, setHovered] = useState(false);
+
+  return (
+    <Box borderBottom>
+      <button
+        type="button"
+        onClick={onToggle}
+        onMouseEnter={() => setHovered(true)}
+        onMouseLeave={() => setHovered(false)}
+        style={{
+          width: '100%',
+          padding: '12px 16px',
+          display: 'flex',
+          alignItems: 'center',
+          justifyContent: 'space-between',
+          background: hovered ? 'var(--bg-hover)' : 'var(--bg-secondary)',
+          transition: 'background-color 150ms',
+          border: 'none',
+          cursor: 'pointer',
+        }}
+      >
+        <Text size="xs" weight="semibold" style={{ textTransform: 'uppercase', letterSpacing: '0.05em' }}>
+          {title}
+        </Text>
+        <ChevronDownIcon
+          style={{
+            width: '16px',
+            height: '16px',
+            color: 'var(--text-tertiary)',
+            transition: 'transform 150ms',
+            transform: expanded ? 'rotate(0deg)' : 'rotate(-90deg)',
+          }}
+        />
+      </button>
+      {expanded && <Box padding="md">{children}</Box>}
+    </Box>
+  );
+}
+
+interface RelatedFieldProps {
+  label: string;
+  description: string;
+  name: string;
+  control: any;
+  register: any;
+}
+
+function RelatedField({
+  label,
+  description,
+  name,
+  control,
+  register,
+}: RelatedFieldProps) {
+  const { fields, append, remove } = useFieldArray({ control, name });
+
+  return (
+    <div style={{ marginBottom: '16px' }}>
+      <Text as="label" size="xs" weight="medium" color="secondary" style={{ display: 'block', marginBottom: '2px' }}>
+        {label}
+      </Text>
+      <Text size="xs" color="tertiary" style={{ marginBottom: '8px', marginTop: 0, fontSize: '10px' }}>{description}</Text>
+      <Stack gap="sm">
+        {fields.map((field, index) => (
+          <Stack key={field.id} direction="row" gap="sm">
+            <input
+              {...register(`${name}.${index}` as const)}
+              style={{ ...inputStyle, flex: 1 }}
+              placeholder="ComponentName"
+            />
+            <Button
+              type="button"
+              variant="ghost"
+              size="sm"
+              onClick={() => remove(index)}
+            >
+              &times;
+            </Button>
+          </Stack>
+        ))}
+        <Button
+          type="button"
+          variant="ghost"
+          size="sm"
+          onClick={() => append("")}
+          style={{ padding: 0, alignSelf: 'flex-start' }}
+        >
+          + Add component
+        </Button>
+      </Stack>
+    </div>
+  );
+}

package/src/components/FragmentRenderer.tsx

@@ -0,0 +1,61 @@
+import type { ReactNode } from "react";
+import {
+  PreviewVariantRuntime,
+  type FragmentVariant,
+} from '@fragments-sdk/core';
+
+interface FragmentRendererProps {
+  /** The variant to render */
+  variant: FragmentVariant;
+  /** Children render function - receives rendered content */
+  children: (content: ReactNode | null, isLoading: boolean, error: Error | null) => ReactNode;
+}
+
+/**
+ * Component that handles async loader execution before rendering a fragment variant.
+ *
+ * If the variant has loaders:
+ * 1. Shows loading state while loaders execute
+ * 2. Merges all loaded data
+ * 3. Passes loaded data to render function
+ *
+ * If no loaders, renders immediately.
+ */
+export function FragmentRenderer({ variant, children }: FragmentRendererProps) {
+  return (
+    <PreviewVariantRuntime variant={variant}>
+      {({ content, isLoading, error }) => children(content, isLoading, error)}
+    </PreviewVariantRuntime>
+  );
+}
+
+/**
+ * Loading indicator for fragment variants with loaders
+ */
+export function LoaderIndicator() {
+  return (
+    <div style={{ display: 'flex', alignItems: 'center', gap: '8px', color: 'var(--text-secondary)', fontSize: '14px' }}>
+      <svg
+        style={{ animation: 'spin 1s linear infinite', width: '16px', height: '16px' }}
+        xmlns="http://www.w3.org/2000/svg"
+        fill="none"
+        viewBox="0 0 24 24"
+      >
+        <circle
+          style={{ opacity: 0.25 }}
+          cx="12"
+          cy="12"
+          r="10"
+          stroke="currentColor"
+          strokeWidth="4"
+        />
+        <path
+          style={{ opacity: 0.75 }}
+          fill="currentColor"
+          d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"
+        />
+      </svg>
+      <span>Running loaders...</span>
+    </div>
+  );
+}

package/src/components/HeaderSearch.tsx

@@ -0,0 +1,24 @@
+import type { RefObject } from "react";
+import { Header, Input } from "@fragments-sdk/ui";
+
+interface HeaderSearchProps {
+  value: string;
+  onChange: (value: string) => void;
+  inputRef: RefObject<HTMLInputElement>;
+}
+
+export function HeaderSearch({ value, onChange, inputRef }: HeaderSearchProps) {
+  return (
+    <Header.Search expandable>
+      <Input
+        ref={inputRef}
+        value={value}
+        onChange={onChange}
+        placeholder="Search components"
+        aria-label="Search components"
+        size="sm"
+        style={{ width: "240px" }}
+      />
+    </Header.Search>
+  );
+}