plass-ui 0.0.1 → 1.0.0

package/dist/internal/styles.d.ts

@@ -3,7 +3,7 @@
  *
  * None of this is exported from `src/index.ts` — it is the library talking to
  * itself. It lives here for one reason: a `size` of `md` has to be 40px on a
- * Button, a TextField, a Select and a Chip, and a table copied into eleven
+ * PlButton, a PlTextField, a Select and a Chip, and a table copied into eleven
  * files is a table that will disagree with itself by the twelfth.
  *
  * The two things that cannot move out of a component are its variant classes
@@ -15,7 +15,7 @@
  * '.'` in `styles.css` covers this folder in the repository and in `dist/`.
  */
 import type * as React from 'react';
-import type { PlassColor, PlassDensity, PlassElevation, PlassSize, PlassVariant } from '../types';
+import type { PlassColor, PlassDensity, PlassElevation, PlassSize, PlassVariant } from '../types.js';
 /**
  * Corner radius — a moulded fillet rather than a chamfer or a pill.
  *
@@ -27,7 +27,7 @@ import type { PlassColor, PlassDensity, PlassElevation, PlassSize, PlassVariant
 export declare const radiusClasses: Record<PlassSize, string>;
 /**
  * The height of a control, and the one number the whole library lines up on:
- * a Button, a TextField, a Select and a Chip of the same `size` sit on the same
+ * a PlButton, a PlTextField, a Select and a Chip of the same `size` sit on the same
  * baseline in the same row.
  *
  * The ladder is 8px per step, and it starts higher than a dense desktop toolkit
@@ -60,10 +60,128 @@ export declare const metaTextClasses: Record<PlassSize, string>;
  * two-pixel nudge.
  */
 export declare const paddingXClasses: Record<PlassDensity, Record<PlassSize, string>>;
+/**
+ * A standalone glyph's box: 14, 16, 20, 24 and 28px.
+ *
+ * Its own ladder rather than a step off `controlHeightClasses`, because an icon
+ * is not a control — it is content, and it is measured against the text it sits
+ * beside rather than against the row it sits in.
+ *
+ * `iconClasses` is the other half of the same idea and is not this: that one
+ * sizes a glyph *inside* a control, in `em`, so it tracks the label it belongs
+ * to. This one is for the glyph that is the whole object.
+ */
+export declare const iconSizeClasses: Record<PlassSize, string>;
+/**
+ * A tick box: the square a PlCheckbox draws and the circle a PlRadioGroup draws.
+ *
+ * Its own ladder rather than a step off `controlHeightClasses`, because a tick
+ * is not a control you can put a label inside — it is an indicator next to one,
+ * and it is sized against the text beside it rather than against the row.
+ */
+export declare const tickSizeClasses: Record<PlassSize, string>;
+/**
+ * And its own radius, well below the control ladder's.
+ *
+ * `--plass-radius-md` is 12px, which on an 18px box is most of the way to a
+ * circle — and a checkbox that is round is a radio button. The intent is the
+ * same fillet as everywhere else, measured against a much smaller object.
+ */
+export declare const tickRadiusClasses: Record<PlassSize, string>;
+/**
+ * The dot inside a checked radio.
+ *
+ * Whole pixels at every step rather than a percentage of the ring around it —
+ * and, which is the half that was missing, whole pixels *of margin* as well.
+ * A diameter can be an exact 7px and still be centred at x.5, because what
+ * decides the offset is `(box − border − border − dot) / 2`: a 7px dot inside
+ * an 18px ring with a 1px edge sits 4.5px from each side, and a circle whose
+ * four sides are antialiased at half coverage reads as "the dot is not
+ * centred" even though the box says it is — and reads as *up and to the left*,
+ * because that is the way the paint rounds.
+ *
+ * So every dot here has the same parity as the ring's content box: 12/6, 14/6,
+ * 16/8, 18/8, 22/10. The ratio wanders between 38% and 44% as a result, which
+ * is the price, and it is invisible next to the thing it buys.
+ */
+export declare const tickDotClasses: Record<PlassSize, string>;
+/**
+ * The line box a tick and its label share.
+ *
+ * Both the tick's wrapper and the label are measured against it: the wrapper is
+ * `h-[1lh]` so the box centres on the label's *first* line rather than on the
+ * whole block, and that only lines up if the two agree on what a line is. Left
+ * to inherit, `1lh` picks up whatever leading the host page happens to set and
+ * the tick drifts a pixel or two off the text beside it.
+ *
+ * It is `controlTextLeadingClasses` and not a ratio of its own, and that is the
+ * whole point of it having moved: a ratio produces a fractional line box at
+ * every step but one — 14px of text at 1.4 is a 19.6px line — and an 18px tick
+ * centred in 19.6px starts at 0.8px, which drags the ring, its edge and the dot
+ * inside it off the pixel grid together. The table's line boxes are whole
+ * numbers with the same parity as the ticks that sit in them (16/14, 18/16,
+ * 20/18, 24/20, 28/24), so every one of those offsets is a whole pixel.
+ *
+ * The label needs no leading of its own; it inherits this one, which is the
+ * only way the two can be guaranteed to agree.
+ */
+export declare const tickRowTextClasses: Record<PlassSize, string>;
+/**
+ * The same two tracks again, as raw lengths.
+ *
+ * These exist for one element: a table cell. `<td>` and `<th>` are among the
+ * very few tags that host stylesheets still style by name — VitePress's
+ * `.vp-doc td`, Tailwind Typography's `.prose td`, every CSS framework ever —
+ * and all of those are two-class selectors that a one-class utility cannot
+ * outrank. A table therefore writes its cell padding inline, where nothing can
+ * reach it.
+ *
+ * Keep these in step with `paddingXClasses`. They are the same numbers: the
+ * Tailwind spacing scale is 0.25rem per step.
+ */
+export declare const paddingXValues: Record<PlassDensity, Record<PlassSize, string>>;
 /** Between a control's own parts — an icon and its label. */
 export declare const gapClasses: Record<PlassSize, string>;
 /** Between a label, the control under it and the text under that. */
 export declare const stackGapClasses: Record<PlassSize, string>;
+/**
+ * A sheet's own padding, which is not a control's.
+ *
+ * `paddingXClasses` is the room a label needs beside the edge of the key it is
+ * printed on. This is the margin a sheet keeps around whatever it is holding,
+ * and it is bigger, because the thing inside is a paragraph rather than a word.
+ * Both axes are offered separately: a sheet with hairlines between its sections
+ * gives its vertical padding away to them.
+ */
+export declare const sheetPaddingXClasses: Record<PlassDensity, Record<PlassSize, string>>;
+export declare const sheetPaddingYClasses: Record<PlassDensity, Record<PlassSize, string>>;
+/**
+ * A sheet's heading: one step above the body, on the same ladder the controls
+ * use, so a card's title lines up with the buttons that end up inside it.
+ */
+export declare const sheetTitleClasses: Record<PlassSize, string>;
+/**
+ * Body copy: the control type scale with the leading opened up, because a
+ * label is one line and a body is a paragraph.
+ */
+export declare const sheetBodyClasses: Record<PlassSize, string>;
+/** Between a sheet's sections, when there are no hairlines to separate them. */
+export declare const sheetSectionGapClasses: Record<PlassSize, string>;
+/**
+ * The hairline that scores a sheet into sections — a card's body from its
+ * footer, one accordion fold from the next, one table row from the next.
+ *
+ * `--plass-divider` and **not** the `--plass-glass-line` the sheet's own edge is
+ * drawn in, which is what this used to be. The edge line is white light caught
+ * on a cut edge, and it reads because what is behind it is the page wash. The
+ * same white laid *across* the middle of the sheet has the sheet behind it
+ * instead, and a white line on a 62%-white pane over a near-white page is not a
+ * line — which is why a light-mode list, card or table had no visible structure
+ * at all unless the host page happened to be drawing its own.
+ */
+export declare const sheetLineClasses = "border-t [border-color:var(--plass-divider)]";
+/** Title to subtitle. Tight — they are one block of text, not two sections. */
+export declare const sheetHeaderGapClasses: Record<PlassSize, string>;
 /**
  * Glass: a translucent fill over a heavily blurred backdrop.
  *
@@ -102,10 +220,45 @@ export declare const transitionClasses: string;
  * its `box-shadow` on the elevation, the tinted glow and the gloss line. A ring
  * would have to be spliced into that chain in each of the three variants, and
  * the first one that forgot would silently lose its focus ring.
+ *
+ * **It is flush.** The offset used to be 2px, and a 2px gap is the one thing a
+ * ring must not have on a control that already draws an edge of its own: a
+ * field, a select, a tick, a switch. The eye reads the field's hairline, then a
+ * band of page, then the ring — three concentric rectangles where there is one
+ * object, and the control looks as though it has come loose from the ring
+ * around it. At offset 0 the outline sits directly on the outside of the edge
+ * and the edge simply thickens and takes the family's colour, which is what
+ * "this one is focused" should look like.
+ *
+ * Nothing is lost on a control with no edge either: the outline is still drawn
+ * entirely *outside* the border box, so on a filled key it is a rim against the
+ * page rather than a band over the fill.
  */
-export declare const focusRingClasses = "focus-visible:[outline:2px_solid_var(--p-ring)] focus-visible:outline-offset-2";
+export declare const focusRingClasses = "focus-visible:[outline:2px_solid_var(--p-ring)] focus-visible:[outline-offset:0px]";
 /** The same ring, drawn by whichever descendant actually takes focus. */
-export declare const focusWithinRingClasses = "has-[:focus-visible]:[outline:2px_solid_var(--p-ring)] has-[:focus-visible]:outline-offset-2";
+export declare const focusWithinRingClasses = "has-[:focus-visible]:[outline:2px_solid_var(--p-ring)] has-[:focus-visible]:[outline-offset:0px]";
+/**
+ * The same ring again, turned inward.
+ *
+ * For an element that is *inside* something that clips — a segment in a
+ * groove, a tab on a rail, a row in a sheet with rounded corners, an accordion
+ * header in a scored pane. A ring drawn outside those is a ring with its top or
+ * its bottom sliced off by the container's own overflow, so it is drawn just
+ * inside the edge instead. Same width, same colour, same absence of a gap.
+ */
+export declare const focusRingInsetClasses = "focus-visible:[outline:2px_solid_var(--p-ring)] focus-visible:[outline-offset:-2px]";
+/**
+ * The × that takes something off a chip.
+ *
+ * Here rather than in `PlChip` because a `PlCombobox` draws the same affordance
+ * on the chips *it* puts in its field, and it cannot reach into the component to
+ * borrow one — Base UI owns that button so the primitive can wire it up. Two
+ * copies of this would be two ×s that stop matching.
+ *
+ * Kept quiet until it is wanted: the glyph sits at 70% until the pointer or the
+ * keyboard arrives.
+ */
+export declare const chipRemoveClasses: string;
 /** Icons track their label rather than carrying a size of their own. */
 export declare const iconClasses = "[&_svg]:pointer-events-none [&_svg]:size-[1.2em] [&_svg]:shrink-0";
 /**
@@ -123,11 +276,16 @@ export declare const srOnlyClasses = "absolute size-px overflow-hidden whitespac
  * The three elevation slots are resolved here rather than in CSS because
  * hovering adds a level and pressing removes one, and doing that arithmetic in
  * a stylesheet would mean four ladders instead of one.
+ *
+ * `variant` is taken for one reason: the two interaction-light slots switch
+ * with it. Light thrown onto a filled surface is white; onto a tinted or a bare
+ * one it has to be the family's own soft tint, or there is nothing for it to
+ * show up against.
  */
-export declare function controlSlots(color: PlassColor, elevation: PlassElevation): React.CSSProperties;
+export declare function controlSlots(color: PlassColor, elevation: PlassElevation, variant: PlassVariant): React.CSSProperties;
 /**
  * The same slots for a surface that **holds** content rather than being
- * pressed: a Box, a Card, a TextField's shell, a popup.
+ * pressed: a Box, a Card, a PlTextField's shell, a popup.
  *
  * There is no `--p-fill` and no `--p-lift` here, and that is the point. A
  * container's sheet is the undyed glass, because what it holds arrives with its
@@ -160,7 +318,29 @@ export declare const disabledClasses: Record<PlassVariant, string>;
  */
 export declare const readOnlyFilterClasses = "saturate-[0.55]";
 /**
- * The shell a field-shaped control is drawn on — a TextField's box and a
+ * The sheet a **container** is drawn on — a PlCard, a PlAccordion, a PlTable, a
+ * PlModal's panel. Everything that holds other people's content rather than
+ * being pressed.
+ *
+ * The three variants say what they say everywhere else, read as a *material*
+ * rather than as an appearance, and the ladder between them is opacity:
+ *
+ * - `solid` — the clear glass at its most opaque. The sheet you cannot see the
+ *   page through, for a panel that has to sit forward of everything around it.
+ *   No border, because a slab that dense has no edge left to catch light on.
+ * - `glass` — the canonical Plass sheet, and the default on every container:
+ *   translucent, blurred, a white hairline round it and the light lying along
+ *   its top edge.
+ * - `ghost` — no sheet at all. For a container inside a container, where a
+ *   second bordered rectangle is a second rectangle.
+ *
+ * None of the three is dyed, and there is no `--p-fill` in `surfaceSlots` to
+ * dye them with. What a container holds arrives with its own colours; the
+ * family reaches the hairline, the focus ring and the caret and stops.
+ */
+export declare const sheetRestClasses: Record<PlassVariant, string>;
+/**
+ * The shell a field-shaped control is drawn on — a PlTextField's box and a
  * Select's trigger, which have to be indistinguishable or a form looks like two
  * different forms stacked on each other.
  *
@@ -171,6 +351,16 @@ export declare const readOnlyFilterClasses = "saturate-[0.55]";
  * **well** — the glass at its most opaque with an inset shadow falling into it,
  * the one shadow in the library that points downward — and the colour family
  * shows up in the hairline, the ring and the caret instead.
+ *
+ * The edge is `--plass-border` and not the sheet's own `--plass-glass-line`,
+ * which is the same correction a PlCheckbox's tick, a PlRadio's ring and a
+ * PlTabs rail already carry, made for the third time and for the last: white
+ * light on a cut edge is a claim about the page wash behind the pane, and a
+ * field is very often *not* on the page — it is on a card, and a white hairline
+ * round a 76%-white box on a white card is a field a reader cannot see the
+ * shape of. A neutral hairline reads on both, and it means every edge on a form
+ * — the tick beside the field, the switch under it, the rail over it — is one
+ * line rather than two kinds of line that only agree on one background.
  */
 export declare const fieldRestClasses: Record<PlassVariant, string>;
 /** The same three, held still. */