@k8slens/element-components 3.3.1

package/README.md

@@ -0,0 +1,124 @@
+# @k8slens/element-components
+
+The React primitives Lens's own interface is built from: thin wrappers over HTML elements, with layout, styling and behaviour supplied by `$props` rather than by stylesheets. Anything built with them inherits the app's spacing scale, colours and theme.
+
+## Installation
+
+```bash
+npm install @k8slens/element-components
+```
+
+## The model
+
+Ordinary props pass through to the DOM. Props prefixed with `$` do not — they are read by plugins:
+
+```tsx
+import { Div, Span, Button } from "@k8slens/element-components";
+
+export const Example = () => (
+  <Div $flex={{ direction: "vertical", gap: "m" }} $padding="l">
+    <Span $font={{ size: "xl", bold: true }}>Hello</Span>
+    <Button $onClick={doTheThing} $tooltip="Does the thing">
+      Do the thing
+    </Button>
+  </Div>
+);
+```
+
+### Elements
+
+`A`, `Button`, `Canvas`, `ClickableDiv`, `ClickableLi`, `Code`, `Dialog`, `Div`, `Form`, `H1`–`H6`, `I`, `Img`, `Input`, `Label`, `Li`, `Nav`, `Ol`, `P`, `Pre`, `Span`, `Svg`, `Table`, `TBody`, `Td`, `TextArea`, `Th`, `Tr`, `Ul`.
+
+### The size scale
+
+Anything taking a size takes a t-shirt size rather than pixels: `zero`, `xxxs`, `xxs`, `xs`, `s`, `m`, `l`, `xl`, `xxl`, `3xl` … `11xl`. One step is 4px.
+
+## The `$props`
+
+Layout
+: `$flex`, `$flexChild`, `$grid`, `$area`, `$areaContent`, `$offset`, `$offsetChildren`, `$block`, `$displayContents`
+
+The box
+: `$size`, `$width`, `$height`, `$margin`, `$padding`, `$border`, `$boxShadow`, `$outline`, `$overflow`
+
+Appearance
+: `$color`, `$backgroundColor`, `$font`, `$textAlign`, `$gradient`, `$tint`, `$grayscale`, `$faded`, `$transition`, `$className`, `$style`
+
+Position and overlays
+: `$relative`, `$absolute`, `$fixed`, `$anchor`, `$anchoredAt`, `$floating`, `$popover`, `$invisibleBackdrop`
+
+Interaction
+: `$onClick`, `$onDoubleClick`, `$onMiddleClick`, `$onRightClick`, `$onOnlyMouseClick`, `$onOutsideClick`, `$cursor`, `$enabled`, `$disabled`
+
+Stateful behaviour
+: `$tooltip`, `$hoverable`, `$hoverableByDragging`, `$focusable`, `$draggable`, `$droppable`, `$dropDownMenu`
+
+Visibility and escape hatches
+: `$hidden`, `$visuallyHidden`, `$noPointerEvents`, `$ref`, `$wrapper`
+
+The types are the reference for each one's values; the sections below cover the ones whose shape is easy to get wrong.
+
+### Colour comes from the theme
+
+Named roles, not literals. Text takes `textDefault`, `textMuted` or `textHighlight`; backgrounds take `backgroundPrimary`, `backgroundSecondary` or `backgroundPrimaryDimmed`; borders take `borderPrimary`. Status and emphasis have roles of their own (`primary`, `success`, `notice`, `warning`, `critical`, `link`, `code`), and the nominal palette (`grey10`…`grey100`, `white`, `inherit`, `transparent`) is available, but a role survives a change to the palette where a nominal grey does not.
+
+```tsx
+<Span $color="textMuted" />
+<Div $backgroundColor="backgroundPrimary" />
+```
+
+### Borders
+
+`color` is a theme role or nominal colour, `width` is on the t-shirt scale, and `radius` is one of `zero`, `s`, `m`, `ml`, `l`, `50`, `full` (or `true` for the default):
+
+```tsx
+<Div $border={{ color: "borderPrimary", width: "xxs", radius: "m" }} $boxShadow />
+```
+
+### Sizes accept a range
+
+The range object's own field is named after its prop — `size` for `$size`, `height` for `$height`, `width` for `$width` — alongside `min` and `max`.
+
+```tsx
+<Div $width="full" $height={{ min: "m", height: "l", max: "xl" }} />
+```
+
+### `$onClick`, not `onClick`
+
+`$onClick` also activates on Enter, and on Space when the element itself is focused, and it respects `$enabled`. Plain `onClick` does neither, which is the usual cause of a control a keyboard user cannot reach.
+
+## Passing `$props` through your own components
+
+Extend the element's props and spread the rest onto the root element, so callers can lay your component out:
+
+```tsx
+import { Div, type DivProps } from "@k8slens/element-components";
+
+interface StatusBadgeProps extends DivProps {
+  readonly status: "success" | "error" | "pending";
+}
+
+export const StatusBadge = ({ status, ...rest }: StatusBadgeProps) => (
+  <Div $flex={{ direction: "horizontal", gap: "s" }} {...rest}>
+    {status}
+  </Div>
+);
+```
+
+Prop types are exported per element: `DivProps`, `ButtonProps`, and so on.
+
+## Styles and registration
+
+The stylesheet is a separate entry point:
+
+```ts
+import "@k8slens/element-components/styles";
+```
+
+The package also exports a Feature, which the application registers:
+
+```ts
+import { elementComponentFeature } from "@k8slens/element-components";
+```
+
+An extension does not register it — the host already has. A unit test that renders these components does need it registered in its container.