{
  "package": "@colineapp/liquid-glass",
  "version": "0.1.0",
  "install": "npm install @colineapp/liquid-glass",
  "summary": "Liquid Glass for the web: the rim refraction, light and motion of iOS 27's glass on any rounded element, with React bindings and tabs whose thumb lifts into a lens. MIT.",
  "rules": [
    "Put the glass first inside a positioned (relative, absolute or fixed), rounded element. It takes the element's corner radius and follows its size.",
    "Paint nothing over it: no background, border or box-shadow on the surface. The glass draws its own edge.",
    "No opacity below 1, filter, mask or backdrop-filter on the surface or its ancestors while the glass shows. Each makes a backdrop root, and the glass would see only that element instead of the page.",
    "To show or hide a surface, fade and zoom its contents, never the surface itself, and call materialize() and dematerialize() for the glass.",
    "Controls on glass get no glass of their own: give the selected or hovered one the liquid-glass-well class.",
    "Rim refraction renders in Chromium. Safari and Firefox get the same material, light and motion without the bend."
  ],
  "groups": [
    {
      "id": "options",
      "title": "Glass options",
      "intro": "Options for `<LiquidGlass />`, `useLiquidGlass(ref, options)`, `createLiquidGlass(element, options)` and `glass.update(options)`. Every option is optional.",
      "entries": [
        {
          "name": "appearance",
          "type": "\"system\" | \"class\" | \"dark\" | \"light\"",
          "default": "\"system\"",
          "description": "`system` follows prefers-color-scheme. `class` is dark while `<html>` has the `dark` class (Tailwind's class strategy, next-themes). `dark` and `light` fix it.",
          "example": "<LiquidGlass appearance=\"class\" />"
        },
        {
          "name": "variant",
          "type": "\"regular\" | \"clear\" | \"lens\"",
          "default": "\"regular\"",
          "description": "`regular` diffuses and evens out the page so text on the glass stays legible over anything. `clear` only bends and lights the page, for glass over media. `lens` is the clear lens a control lifts into; pair it with `geometry: LENS_GEOMETRY`.",
          "example": "<LiquidGlass variant=\"clear\" />"
        },
        {
          "name": "floating",
          "type": "boolean | \"dialog\"",
          "default": "false",
          "description": "For menus, popovers, dialogs and sheets. Floating glass diffuses the page more, as iOS 27's does, so text beneath washes into soft colour, and the surface casts a drop shadow (`--liquid-glass-shadow`). `\"dialog\"` casts a dialog's deeper shadow (`--liquid-glass-dialog-shadow`).",
          "example": "<LiquidGlass floating=\"dialog\" />"
        },
        {
          "name": "interactive",
          "type": "boolean",
          "default": "false",
          "description": "For glass that holds controls, like SwiftUI's `.glassEffect(.regular.interactive())`: the pointer warms the glass beneath it, and a press blooms out from there.",
          "example": "<LiquidGlass interactive />"
        },
        {
          "name": "swell",
          "type": "boolean",
          "default": "false",
          "description": "For glass you press, like a search field: pressed, the surface swells about its centre on the tabs' spring and springs back with a slight overshoot on release.",
          "example": "<LiquidGlass interactive swell />"
        },
        {
          "name": "tint",
          "type": "string",
          "default": "near-black in dark, white in light",
          "description": "Colour washed over the body by the tone's `tint` share (50% on dark regular glass, 40% on light). Any CSS colour, including `var()`.",
          "example": "<LiquidGlass tint=\"var(--background)\" />"
        },
        {
          "name": "hue",
          "type": "string | null",
          "default": "null",
          "description": "A colour whose hue the glass takes on, like tinted iOS glass: each pixel beneath shifts toward the hue at its own brightness, so colours behind keep their chroma. Any concrete CSS colour; neutral colours leave the glass untinted.",
          "example": "<LiquidGlass hue=\"#3d6bff\" />"
        },
        {
          "name": "hueStrength",
          "type": "number (0–1)",
          "default": "1 on light glass, 0.5 on dark",
          "description": "How much of the hue the glass takes.",
          "example": "<LiquidGlass hue=\"#ff4fa3\" hueStrength={0.7} />"
        },
        {
          "name": "geometry",
          "type": "Partial<GlassGeometry>",
          "default": "DEFAULT_GEOMETRY",
          "description": "The rim's shape, measured from iOS 27: its width and depth, how steeply it bends, the darkened edge and the glints. See the geometry fields below. `LENS_GEOMETRY` is the rim for a control-high lens.",
          "example": "<LiquidGlass geometry={{ maxFall: 0.5, edge: 1 }} />"
        },
        {
          "name": "tone",
          "type": "{ dark?: Partial<GlassTone>; light?: Partial<GlassTone> }",
          "description": "Per-appearance overrides of the variant's filters: body `blur`, `floatingBlur`, `saturate`, `contrast`, `brightness`, `tint` share, and the rim's `highlightContrast`, `highlightBrightness`, `shadeBrightness`, `glowSaturate`, `glowBrightness`, `edgeBrightness`.",
          "example": "<LiquidGlass tone={{ dark: { brightness: 0.4 }, light: { tint: 0.5 } }} />"
        },
        {
          "name": "fit",
          "type": "\"box\" | \"fixed\" | \"scroll\"",
          "default": "\"box\"",
          "description": "`box` fills the surface. `fixed` fills the nearest containing block for fixed elements, such as a transformed popper wrapper, so the glass holds still while the surface scrolls its own content. `scroll` spans the surface's whole scroll height, for a dialog or sheet that scrolls itself.",
          "example": "<LiquidGlass fit=\"scroll\" floating=\"dialog\" />"
        },
        {
          "name": "refraction",
          "type": "boolean",
          "default": "true",
          "description": "Bend the page at the rim. Rim refraction needs SVG filters in backdrop-filter, which only Chromium renders; Safari and Firefox keep the material without the bend either way.",
          "example": "<LiquidGlass refraction={false} />"
        },
        {
          "name": "samples",
          "type": "1 | 4",
          "default": "1",
          "description": "Refraction samples per pixel. 4 antialiases the bend, so edges it stretches don't stair-step as the glass moves. It costs four displacement passes, so keep it for small glass with nothing blurring its backdrop, like a lens.",
          "example": "<LiquidGlass variant=\"lens\" samples={4} />"
        }
      ]
    },
    {
      "id": "geometry",
      "title": "Geometry fields",
      "intro": "Fields of `GlassGeometry`, in CSS pixels unless noted. Pass any subset as `geometry`.",
      "entries": [
        {
          "name": "bezel",
          "type": "number",
          "default": "17",
          "description": "Width of the refracting rim along the top and bottom. The centre is flat."
        },
        {
          "name": "thickness",
          "type": "number",
          "default": "24",
          "description": "Glass depth under the top and bottom rims. Deeper glass bends further."
        },
        {
          "name": "sideBezel",
          "type": "number",
          "default": "27",
          "description": "Width of the refracting rim at the sides and rounded ends."
        },
        {
          "name": "sideThickness",
          "type": "number",
          "default": "44",
          "description": "Glass depth under the sides and rounded ends."
        },
        {
          "name": "refractiveIndex",
          "type": "number",
          "default": "1.5",
          "description": "The glass's refractive index, for Snell's law at the rim."
        },
        {
          "name": "maxFall",
          "type": "number (0–1)",
          "default": "0.8",
          "description": "Rim bend: the steepest the rim's shift may fall per pixel inward. Where it falls, the rim magnifies what is beneath by 1 / (1 − maxFall), so lower values bend more gently and keep text crossing the rim from smearing. The tab lens uses 0.3. Past 1 the lens folds content into mirrored echoes."
        },
        {
          "name": "edge",
          "type": "number",
          "default": "0.75",
          "description": "Width of iOS 27's darkened edge, a contour where the glass meets the air, with the hairline just inside it. 0 leaves it out."
        },
        {
          "name": "glint",
          "type": "number (0–1)",
          "default": "0.4",
          "description": "Share of the hairline's light that gathers into glints where the light catches the curve, at the top-left and, fainter, the bottom-right. 0 keeps an even band."
        },
        {
          "name": "hairline",
          "type": "number",
          "default": "1",
          "description": "Rim hairline width."
        },
        {
          "name": "hairlineSides",
          "type": "number (0–1)",
          "default": "0.15",
          "description": "Share of the hairline's strength that reaches the sides."
        },
        {
          "name": "shadeWidth",
          "type": "number",
          "default": "1",
          "description": "Width of the darkened sides."
        },
        {
          "name": "glowReach",
          "type": "number",
          "default": "8",
          "description": "How far the inner glow reaches in from the top and bottom rims."
        },
        {
          "name": "glowBottom",
          "type": "number (0–1)",
          "default": "0.5",
          "description": "Bottom glow strength relative to the top."
        }
      ]
    },
    {
      "id": "handle",
      "title": "The glass handle",
      "intro": "`createLiquidGlass()` and `attachLiquidGlass()` return it; `useLiquidGlass()` returns a ref to it, and `<LiquidGlass glassRef={ref} />` fills one.",
      "entries": [
        {
          "name": "update(options)",
          "type": "(options: LiquidGlassOptions) => void",
          "description": "Replaces the options. Cheap: the rim only rebuilds when the geometry changes.",
          "example": "glass.update({ variant: \"clear\" });"
        },
        {
          "name": "magnify(factor)",
          "type": "(factor: number) => void",
          "description": "Magnifies what is beneath the glass about its centre, as a raised lens does (1 for none), and sharpens it so it doesn't come out soft. Cheap enough to call every frame. Needs refraction.",
          "example": "glass.magnify(1.1);"
        },
        {
          "name": "materialize(timing?)",
          "type": "(timing?: { duration?, easing?, delay?, scale? }) => Promise<void>",
          "description": "Grows the glass from clear to its tone, for surfaces that appear. Fade the surface's contents, never the surface: opacity below 1 hides the glass. For a surface that zooms open, scale its contents and pass the same `scale`; the glass grows by its inset instead.",
          "example": "await glass.materialize({ duration: 240, scale: 0.96 });"
        },
        {
          "name": "dematerialize(timing?)",
          "type": "(timing?) => Promise<void>",
          "description": "Fades the glass back to clear and holds it there, for surfaces that leave. Wells on it ease back with it.",
          "example": "await glass.dematerialize({ duration: 160 });"
        },
        {
          "name": "destroy()",
          "type": "() => void",
          "description": "Removes the glass and its filters."
        },
        {
          "name": "element",
          "type": "HTMLElement",
          "description": "The glass element, the surface's first child."
        },
        {
          "name": "appearance",
          "type": "\"dark\" | \"light\"",
          "description": "The resolved appearance."
        }
      ]
    },
    {
      "id": "tabs",
      "title": "Tabs",
      "intro": "`useLiquidGlassTabs(trackRef, options)` in React, `attachLiquidGlassTabs(track, options)` without it. The track is the tabs' positioned, rounded container. Your tabs and selection stay yours; the thumb follows the selected tab, lifts into a lens that magnifies the labels, stretches as it travels and squashes as it lands. Dragging the selected tab scrubs across the others. Returns `{ update(), destroy() }`.",
      "entries": [
        {
          "name": "appearance",
          "type": "\"system\" | \"class\" | \"dark\" | \"light\"",
          "default": "\"system\"",
          "description": "As for glass."
        },
        {
          "name": "orientation",
          "type": "\"horizontal\" | \"vertical\"",
          "default": "\"horizontal\"",
          "description": "Vertical tabs stack and don't scrub."
        },
        {
          "name": "tabs",
          "type": "string",
          "default": "'[role=\"tab\"]'",
          "description": "Selector for the tabs inside the track.",
          "example": "useLiquidGlassTabs(track, { tabs: '[role=\"radio\"]' });"
        },
        {
          "name": "isSelected",
          "type": "(tab: HTMLElement) => boolean",
          "default": "aria-selected, aria-checked or data-state=\"active\"",
          "description": "Whether a tab is selected. The thumb follows changes to the default attributes by itself; call `update()` after changes to anything else."
        },
        {
          "name": "onSelect",
          "type": "(tab: HTMLElement) => void",
          "default": "press and click the tab",
          "description": "Selects the tab the thumb was dragged onto."
        },
        {
          "name": "glass",
          "type": "boolean | LiquidGlassOptions",
          "default": "glass unless on another glass surface",
          "description": "The track's own glass, or its options. On another glass surface the track gets none of its own: it becomes a recessed tint and the thumb a well in that glass."
        },
        {
          "name": "refraction",
          "type": "boolean",
          "default": "true",
          "description": "Bend the page at the rims."
        }
      ]
    },
    {
      "id": "react",
      "title": "React",
      "intro": "From `@colineapp/liquid-glass/react`. React 18 or later; the core package has no dependencies.",
      "entries": [
        {
          "name": "<LiquidGlass />",
          "type": "LiquidGlassOptions & { className?, style?, children?, glassRef? }",
          "description": "Glass behind a surface's content. Render it first inside a positioned, rounded element. `glassRef` receives the handle, for materialize() and magnify().",
          "example": "<nav className=\"relative rounded-full px-6 py-3\">\n  <LiquidGlass interactive />\n  …\n</nav>"
        },
        {
          "name": "useLiquidGlass(ref, options)",
          "type": "RefObject<LiquidGlass | null>",
          "description": "Turns an element you already render into a glass surface; the glass is inserted as its first child."
        },
        {
          "name": "useLiquidGlassTabs(ref, options)",
          "type": "RefObject<LiquidGlassTabs | null>",
          "description": "Liquid Glass tabs on a track you render. See Tabs."
        }
      ]
    },
    {
      "id": "css",
      "title": "CSS",
      "intro": "Import `@colineapp/liquid-glass/styles.css` once. The filters themselves are set inline by the script, as literal values Safari can read.",
      "entries": [
        {
          "name": ".liquid-glass-well",
          "type": "class",
          "description": "For a selected or hovered control on a glass surface: brightens the glass beneath it (dimmer in light), instead of glass on glass.",
          "example": "<button className=\"liquid-glass-well rounded-full\">Today</button>"
        },
        {
          "name": "--liquid-glass-shadow",
          "type": "custom property",
          "description": "The shadow floating glass casts. Set it on the surface or an ancestor."
        },
        {
          "name": "--liquid-glass-dialog-shadow",
          "type": "custom property",
          "description": "The deeper shadow of `floating: \"dialog\"` glass."
        }
      ]
    }
  ],
  "examples": [
    {
      "id": "react",
      "title": "A glass toolbar in React",
      "description": "Render <LiquidGlass /> first inside a positioned, rounded element.",
      "language": "tsx",
      "code": "import { LiquidGlass } from \"@colineapp/liquid-glass/react\";\nimport \"@colineapp/liquid-glass/styles.css\";\n\nexport function Toolbar() {\n  return (\n    <nav className=\"relative flex gap-1 rounded-full p-1.5\">\n      <LiquidGlass appearance=\"class\" interactive />\n      <button className=\"liquid-glass-well rounded-full px-4 py-2\">Today</button>\n      <button className=\"rounded-full px-4 py-2\">Week</button>\n    </nav>\n  );\n}"
    },
    {
      "id": "vanilla",
      "title": "Without React",
      "description": "createLiquidGlass inserts the glass as the element's first child.",
      "language": "ts",
      "code": "import { createLiquidGlass } from \"@colineapp/liquid-glass\";\nimport \"@colineapp/liquid-glass/styles.css\";\n\nconst glass = createLiquidGlass(document.querySelector(\".toolbar\")!, {\n  interactive: true,\n});\n\nglass.update({ variant: \"clear\" });\nglass.destroy();"
    },
    {
      "id": "tabs",
      "title": "Pill tabs",
      "description": "Your tabs, your selection; the thumb follows aria-selected.",
      "language": "tsx",
      "code": "import { useRef } from \"react\";\nimport { useLiquidGlassTabs } from \"@colineapp/liquid-glass/react\";\n\nexport function Period({ value, onChange }: { value: string; onChange: (value: string) => void }) {\n  const track = useRef<HTMLDivElement>(null);\n  useLiquidGlassTabs(track, { appearance: \"class\" });\n  return (\n    <div ref={track} role=\"tablist\" className=\"flex rounded-full p-1\">\n      {[\"Day\", \"Week\", \"Month\"].map((label) => (\n        <button key={label} role=\"tab\" aria-selected={label === value} onClick={() => onChange(label)}\n          className=\"rounded-full px-4 py-1.5 text-sm font-medium\">\n          {label}\n        </button>\n      ))}\n    </div>\n  );\n}"
    },
    {
      "id": "menu",
      "title": "A menu that materializes",
      "description": "Fade the contents, never the surface; the glass grows from clear.",
      "language": "tsx",
      "code": "import { useEffect, useRef, useState } from \"react\";\nimport { LiquidGlass, type LiquidGlassHandle } from \"@colineapp/liquid-glass/react\";\n\nexport function Menu({ open, items }: { open: boolean; items: string[] }) {\n  const glass = useRef<LiquidGlassHandle | null>(null);\n  const [active, setActive] = useState(-1);\n  useEffect(() => {\n    if (open) void glass.current?.materialize({ duration: 240, scale: 0.96 });\n  }, [open]);\n  if (!open) return null;\n  return (\n    <div role=\"menu\" className=\"absolute right-0 top-12 w-56 rounded-2xl p-1.5\">\n      <LiquidGlass glassRef={glass} appearance=\"class\" floating />\n      {items.map((item, index) => (\n        <button key={item} role=\"menuitem\" onPointerEnter={() => setActive(index)}\n          className={`w-full rounded-xl px-3 py-2 text-left ${index === active ? \"liquid-glass-well\" : \"\"}`}>\n          {item}\n        </button>\n      ))}\n    </div>\n  );\n}"
    },
    {
      "id": "dialog",
      "title": "A glass dialog",
      "description": "floating=\"dialog\" casts the deeper shadow; the glass materializes as the contents zoom in.",
      "language": "tsx",
      "code": "import { useLayoutEffect, useRef } from \"react\";\nimport { LiquidGlass, type LiquidGlassHandle } from \"@colineapp/liquid-glass/react\";\n\nexport function ShareDialog({ onClose }: { onClose: () => void }) {\n  const glass = useRef<LiquidGlassHandle | null>(null);\n  useLayoutEffect(() => {\n    void glass.current?.materialize({ duration: 280, scale: 0.95 });\n  }, []);\n  const close = () => void glass.current?.dematerialize({ duration: 180, scale: 0.97 }).then(onClose);\n  return (\n    <div role=\"dialog\" aria-modal=\"true\" className=\"fixed left-1/2 top-1/3 w-80 -translate-x-1/2 rounded-[28px] p-5\">\n      <LiquidGlass glassRef={glass} appearance=\"class\" floating=\"dialog\" />\n      <h2 className=\"font-semibold\">Share this album</h2>\n      <button className=\"liquid-glass-well mt-4 h-10 w-full rounded-full\" onClick={close}>Copy link</button>\n    </div>\n  );\n}"
    },
    {
      "id": "search",
      "title": "A search field that swells",
      "description": "interactive lights it under the pointer; swell springs it on press.",
      "language": "tsx",
      "code": "<label className=\"relative flex h-11 items-center gap-2 rounded-full px-4\">\n  <LiquidGlass appearance=\"class\" interactive swell />\n  <SearchIcon />\n  <input className=\"bg-transparent outline-none\" placeholder=\"Search\" />\n</label>"
    },
    {
      "id": "lens",
      "title": "A magnifying lens",
      "description": "The tab lens on its own: the lens variant, its geometry, four samples and magnify().",
      "language": "tsx",
      "code": "import { useRef } from \"react\";\nimport { LENS_GEOMETRY } from \"@colineapp/liquid-glass\";\nimport { LiquidGlass, type LiquidGlassHandle } from \"@colineapp/liquid-glass/react\";\n\nexport function Lens() {\n  const lens = useRef<LiquidGlassHandle | null>(null);\n  return (\n    <div\n      className=\"absolute size-24 rounded-full\"\n      onPointerDown={() => lens.current?.magnify(1.15)}\n      onPointerUp={() => lens.current?.magnify(1)}\n    >\n      <LiquidGlass glassRef={lens} appearance=\"class\" variant=\"lens\" geometry={LENS_GEOMETRY} samples={4} />\n    </div>\n  );\n}"
    }
  ]
}