// src/components/docs/specs/SpecsOverlaysPage.tsx
import Link from "@contractspec/lib.ui-link";
import { ChevronRight } from "lucide-react";
import { jsx, jsxs } from "react/jsx-runtime";
function SpecsOverlaysPage() {
  return /* @__PURE__ */ jsxs("div", {
    className: "space-y-8",
    children: [
      /* @__PURE__ */ jsxs("div", {
        className: "space-y-4",
        children: [
          /* @__PURE__ */ jsx("h1", {
            className: "text-4xl font-bold",
            children: "Overlays"
          }),
          /* @__PURE__ */ jsxs("p", {
            className: "text-muted-foreground",
            children: [
              "An ",
              /* @__PURE__ */ jsx("strong", {
                children: "OverlaySpec"
              }),
              " allows tenants or users to customize UI layouts and field visibility without modifying the underlying application code. Overlays are cryptographically signed to ensure they respect policy boundaries and cannot introduce security vulnerabilities."
            ]
          })
        ]
      }),
      /* @__PURE__ */ jsxs("div", {
        className: "space-y-4",
        children: [
          /* @__PURE__ */ jsx("h2", {
            className: "text-2xl font-bold",
            children: "Why overlays matter"
          }),
          /* @__PURE__ */ jsx("p", {
            className: "text-muted-foreground",
            children: "Different users have different needs. A power user might want to see all available fields and actions, while a casual user prefers a simplified interface. A tenant in a multi-tenant application might want to brand the UI or hide features they don't use."
          }),
          /* @__PURE__ */ jsx("p", {
            className: "text-muted-foreground",
            children: "Traditional approaches require either building multiple UIs or adding complex configuration logic throughout the codebase. OverlaySpecs provide a safer, more maintainable solution: users can customize their experience, but only within the bounds allowed by the underlying specs and policies."
          })
        ]
      }),
      /* @__PURE__ */ jsxs("div", {
        className: "space-y-4",
        children: [
          /* @__PURE__ */ jsx("h2", {
            className: "text-2xl font-bold",
            children: "What overlays can do"
          }),
          /* @__PURE__ */ jsxs("ul", {
            className: "text-muted-foreground list-inside list-disc space-y-2",
            children: [
              /* @__PURE__ */ jsxs("li", {
                children: [
                  /* @__PURE__ */ jsx("strong", {
                    children: "Hide or show fields"
                  }),
                  " – Remove fields from forms or detail views (but only if the user has permission to see them in the first place)"
                ]
              }),
              /* @__PURE__ */ jsxs("li", {
                children: [
                  /* @__PURE__ */ jsx("strong", {
                    children: "Reorder fields"
                  }),
                  " – Change the order in which fields appear"
                ]
              }),
              /* @__PURE__ */ jsxs("li", {
                children: [
                  /* @__PURE__ */ jsx("strong", {
                    children: "Rename labels"
                  }),
                  " – Use different terminology that's more familiar to the user"
                ]
              }),
              /* @__PURE__ */ jsxs("li", {
                children: [
                  /* @__PURE__ */ jsx("strong", {
                    children: "Change layouts"
                  }),
                  " – Switch between list, grid, or card views"
                ]
              }),
              /* @__PURE__ */ jsxs("li", {
                children: [
                  /* @__PURE__ */ jsx("strong", {
                    children: "Add help text"
                  }),
                  " – Provide context-specific guidance"
                ]
              }),
              /* @__PURE__ */ jsxs("li", {
                children: [
                  /* @__PURE__ */ jsx("strong", {
                    children: "Set default values"
                  }),
                  " – Pre-fill forms with tenant-specific defaults"
                ]
              }),
              /* @__PURE__ */ jsxs("li", {
                children: [
                  /* @__PURE__ */ jsx("strong", {
                    children: "Apply branding"
                  }),
                  " – Customize colors, logos, and styling (within approved themes)"
                ]
              })
            ]
          })
        ]
      }),
      /* @__PURE__ */ jsxs("div", {
        className: "space-y-4",
        children: [
          /* @__PURE__ */ jsx("h2", {
            className: "text-2xl font-bold",
            children: "Example OverlaySpec"
          }),
          /* @__PURE__ */ jsx("p", {
            className: "text-muted-foreground",
            children: "Here's an overlay that customizes an order form:"
          }),
          /* @__PURE__ */ jsx("div", {
            className: "bg-background/50 border-border text-muted-foreground overflow-x-auto rounded-lg border p-4 font-mono text-sm",
            children: /* @__PURE__ */ jsx("pre", {
              children: `overlayId: acme-order-form
version: '1.0.0'.0.0
appliesTo:
  capability: createOrder
  tenantId: acme-corp
  
modifications:
  - type: hideField
    field: internalNotes
    reason: "ACME doesn't use internal notes"
    
  - type: renameLabel
    field: customerReference
    newLabel: "PO Number"
    
  - type: reorderFields
    fields:
      - customerReference
      - items
      - shippingAddress
      - billingAddress
      - paymentMethod
      
  - type: setDefault
    field: paymentMethod
    value: "net30"
    
  - type: addHelpText
    field: customerReference
    text: "Enter your purchase order number from your procurement system"
    
  - type: makeRequired
    field: customerReference
    
signature:
  algorithm: EdDSA
  publicKey: "acme-corp-overlay-key"
  signature: "base64-encoded-signature"`
            })
          })
        ]
      }),
      /* @__PURE__ */ jsxs("div", {
        className: "space-y-4",
        children: [
          /* @__PURE__ */ jsx("h2", {
            className: "text-2xl font-bold",
            children: "Safety guarantees"
          }),
          /* @__PURE__ */ jsx("p", {
            className: "text-muted-foreground",
            children: "Overlays are powerful, but they must not compromise security or data integrity. ContractSpec enforces several guarantees:"
          }),
          /* @__PURE__ */ jsxs("ul", {
            className: "text-muted-foreground list-inside list-disc space-y-2",
            children: [
              /* @__PURE__ */ jsxs("li", {
                children: [
                  /* @__PURE__ */ jsx("strong", {
                    children: "Overlays cannot grant new permissions"
                  }),
                  " – They can only hide or rearrange what the user is already allowed to see"
                ]
              }),
              /* @__PURE__ */ jsxs("li", {
                children: [
                  /* @__PURE__ */ jsx("strong", {
                    children: "Overlays cannot bypass validation"
                  }),
                  " – Field types, constraints, and business rules from the underlying spec still apply"
                ]
              }),
              /* @__PURE__ */ jsxs("li", {
                children: [
                  /* @__PURE__ */ jsx("strong", {
                    children: "Overlays must be signed"
                  }),
                  " – Only authorized parties (typically tenant admins) can create overlays"
                ]
              }),
              /* @__PURE__ */ jsxs("li", {
                children: [
                  /* @__PURE__ */ jsx("strong", {
                    children: "Overlays are versioned"
                  }),
                  " – Changes to overlays are tracked and can be rolled back"
                ]
              }),
              /* @__PURE__ */ jsxs("li", {
                children: [
                  /* @__PURE__ */ jsx("strong", {
                    children: "Overlays are audited"
                  }),
                  " – Every overlay application is logged"
                ]
              })
            ]
          })
        ]
      }),
      /* @__PURE__ */ jsxs("div", {
        className: "space-y-4",
        children: [
          /* @__PURE__ */ jsx("h2", {
            className: "text-2xl font-bold",
            children: "Creating overlays"
          }),
          /* @__PURE__ */ jsx("p", {
            className: "text-muted-foreground",
            children: "Overlays can be created through:"
          }),
          /* @__PURE__ */ jsxs("ul", {
            className: "text-muted-foreground list-inside list-disc space-y-2",
            children: [
              /* @__PURE__ */ jsxs("li", {
                children: [
                  /* @__PURE__ */ jsx("strong", {
                    children: "Visual editor"
                  }),
                  " – A drag-and-drop interface for non-technical users"
                ]
              }),
              /* @__PURE__ */ jsxs("li", {
                children: [
                  /* @__PURE__ */ jsx("strong", {
                    children: "TypeScript/JSON"
                  }),
                  " – For developers who prefer code"
                ]
              }),
              /* @__PURE__ */ jsxs("li", {
                children: [
                  /* @__PURE__ */ jsx("strong", {
                    children: "API"
                  }),
                  " – Programmatically create overlays for automation"
                ]
              })
            ]
          }),
          /* @__PURE__ */ jsx("p", {
            className: "text-muted-foreground",
            children: "Once created, overlays must be signed using a private key. The corresponding public key is registered with ContractSpec, which verifies the signature before applying the overlay."
          }),
          /* @__PURE__ */ jsxs("p", {
            className: "text-muted-foreground",
            children: [
              "See",
              " ",
              /* @__PURE__ */ jsx(Link, {
                href: "/docs/libraries/overlay-engine",
                className: "text-violet-400 underline",
                children: "Overlay Engine docs"
              }),
              " ",
              "and the",
              " ",
              /* @__PURE__ */ jsx(Link, {
                href: "/docs/advanced/overlay-editor",
                className: "text-violet-400 underline",
                children: "Overlay Editor guide"
              }),
              " ",
              "for end-to-end workflows."
            ]
          })
        ]
      }),
      /* @__PURE__ */ jsxs("div", {
        className: "space-y-4",
        children: [
          /* @__PURE__ */ jsx("h2", {
            className: "text-2xl font-bold",
            children: "Overlay scope"
          }),
          /* @__PURE__ */ jsx("p", {
            className: "text-muted-foreground",
            children: "Overlays can be scoped to:"
          }),
          /* @__PURE__ */ jsxs("ul", {
            className: "text-muted-foreground list-inside list-disc space-y-2",
            children: [
              /* @__PURE__ */ jsxs("li", {
                children: [
                  /* @__PURE__ */ jsx("strong", {
                    children: "Tenant"
                  }),
                  " – All users in a tenant see the same overlay"
                ]
              }),
              /* @__PURE__ */ jsxs("li", {
                children: [
                  /* @__PURE__ */ jsx("strong", {
                    children: "User"
                  }),
                  " – Individual users can have personal overlays"
                ]
              }),
              /* @__PURE__ */ jsxs("li", {
                children: [
                  /* @__PURE__ */ jsx("strong", {
                    children: "Role"
                  }),
                  " – All users with a specific role see the overlay"
                ]
              }),
              /* @__PURE__ */ jsxs("li", {
                children: [
                  /* @__PURE__ */ jsx("strong", {
                    children: "Device"
                  }),
                  " – Different overlays for mobile vs desktop"
                ]
              })
            ]
          }),
          /* @__PURE__ */ jsx("p", {
            className: "text-muted-foreground",
            children: "If multiple overlays apply to the same user, they are merged in order of specificity (user overlays override role overlays, which override tenant overlays)."
          })
        ]
      }),
      /* @__PURE__ */ jsxs("div", {
        className: "space-y-4",
        children: [
          /* @__PURE__ */ jsx("h2", {
            className: "text-2xl font-bold",
            children: "Best practices"
          }),
          /* @__PURE__ */ jsxs("ul", {
            className: "text-muted-foreground list-inside list-disc space-y-2",
            children: [
              /* @__PURE__ */ jsx("li", {
                children: "Start with the default UI and only create overlays when users request specific changes."
              }),
              /* @__PURE__ */ jsx("li", {
                children: "Document why each overlay modification was made—this helps when reviewing or updating overlays."
              }),
              /* @__PURE__ */ jsx("li", {
                children: "Test overlays thoroughly to ensure they don't break workflows or confuse users."
              }),
              /* @__PURE__ */ jsx("li", {
                children: "Use tenant-level overlays for organizational customizations and user-level overlays for personal preferences."
              }),
              /* @__PURE__ */ jsx("li", {
                children: "Regularly review overlays to remove ones that are no longer needed."
              }),
              /* @__PURE__ */ jsx("li", {
                children: "Protect overlay signing keys carefully—they control what customizations are allowed."
              })
            ]
          })
        ]
      }),
      /* @__PURE__ */ jsxs("div", {
        className: "flex items-center gap-4 pt-4",
        children: [
          /* @__PURE__ */ jsx(Link, {
            href: "/docs/specs/policy",
            className: "btn-ghost",
            children: "Previous: Policy"
          }),
          /* @__PURE__ */ jsxs(Link, {
            href: "/docs/safety",
            className: "btn-primary",
            children: [
              "Next: Safety ",
              /* @__PURE__ */ jsx(ChevronRight, {
                size: 16
              })
            ]
          })
        ]
      })
    ]
  });
}
export {
  SpecsOverlaysPage
};
