@estiva-app/ui 0.21.1 → 0.22.0

package/src/Avatar.tsx

@@ -29,6 +29,9 @@ import { cn } from './cn'
  */
 const HUES = ['#56c8ff', '#ff8f6b', '#4ade8c', '#b18cff', '#ffc94d', '#ff7eb0', '#7ea8ff', '#5fdfd6']
 
+/** The colour a person's initials sit on, chosen from a key: the same key
+ *  always gives the same hue, so a face reads as theirs in every app. The
+ *  eight are a fallback palette, not tokens — see the note above `HUES`. */
 export const hueFor = (key: string) => {
   let h = 0
   for (let i = 0; i < key.length; i++) h = (h * 31 + key.charCodeAt(i)) | 0

package/src/ChipInput.tsx

@@ -54,6 +54,9 @@ export interface InputChipProps {
   className?: string
 }
 
+/** A chip standing on its own: a label, an optional leading icon, an optional
+ *  ✕. For a caller that keeps its own list. Inside a `ChipInput` the same look
+ *  goes onto Base UI's `Combobox.Chip`, which joins the field's keyboard. */
 export function InputChip({ label, leading, onRemove, removeLabel, truncate, className }: InputChipProps) {
   return (
     <div className={cn(CHIP_BOX, chipPadding(!!leading, !!onRemove), className)}>

package/src/CommandPalette.tsx

@@ -237,6 +237,9 @@ export interface CommandPaletteSearchProps {
 
 type ListGroup = { value: string; items: CommandPaletteRow[] }
 
+/** The palette as a search: a query field, rows in labelled groups walked with
+ *  the arrow keys, and what to show while nothing has arrived and when nothing
+ *  matches. */
 export function CommandPaletteSearch({ query, onQueryChange, placeholder, groups, chip, pending, notes = [], empty, children }: CommandPaletteSearchProps) {
   const { modKey, popupRef } = usePalette('CommandPaletteSearch')
   const back = useBack(chip, popupRef)
@@ -478,6 +481,9 @@ function isTextField(el: Element | null): el is HTMLInputElement | HTMLTextAreaE
   return el instanceof HTMLInputElement && TEXT_TYPES.has(el.getAttribute('type') ?? '') && el.getAttribute('role') !== 'combobox' && el.tabIndex >= 0
 }
 
+/** The palette as a form: fields, one submit button, and Ctrl+Enter — both ways
+ *  in run Base UI's field check. It shows what it is working on and what failed,
+ *  and sends focus to the first field that needs something. */
 export function CommandPaletteForm({ chip, icon, submitLabel, onSubmit, submitWaits, working, error, children }: CommandPaletteFormProps) {
   const { modKey, popupRef } = usePalette('CommandPaletteForm')
   const back = useBack(chip, popupRef)

package/src/IdentityMenu.tsx

@@ -62,6 +62,9 @@ export interface IdentityPanelProps extends Omit<IdentityMenuProps, 'compact'> {
   onClose?: () => void
 }
 
+/** The identity rows on a panel of their own, with no menu around them — for a
+ *  docs page, or anywhere the panel is already placed. `IdentityMenu` is the
+ *  same rows inside a real menu. */
 export function IdentityPanel({ className, onClose = () => {}, ...rest }: IdentityPanelProps) {
   return (
     <MenuPanel className={cn('w-72', className)}>

package/src/Menu.tsx

@@ -86,6 +86,10 @@ export interface MenuPanelProps extends Omit<ComponentPropsWithRef<'div'>, 'chil
   children?: ReactNode
 }
 
+/** The menu's surface without the menu: the elevated box, the rows' padding,
+ *  and a divider that runs the full width of what it separates. `Menu` renders
+ *  its popup as one. On its own it is for the places that draw a menu's look
+ *  but not its behaviour — a docs page, Peek's `@`, `/` and `[` pickers. */
 export function MenuPanel({ children, className, ...props }: MenuPanelProps) {
   return (
     <div
@@ -277,6 +281,9 @@ export interface MenuSubProps {
   className?: string
 }
 
+/** A row that opens another menu beside it; its rows are this row's children.
+ *  Never inside a menu opened on hover — leaving the submenu strands both open,
+ *  measured below. */
 export function MenuSub({ label, leading, selected, children, className }: MenuSubProps) {
   /*
    * A submenu inside a hover-opened menu strands it.

package/src/Skeleton.tsx

@@ -10,6 +10,8 @@ import { cn } from './cn'
  * A list reveals after 150ms (`animate-skeleton-in`, in the preset) so a
  * fast load never flashes a skeleton — Peek's rule.
  */
+/** One pulsing bar at the inset colour: the piece every placeholder here is
+ *  built from. It draws nothing of its own — give it a width and a height. */
 export function SkeletonBar({ className, style }: { className?: string; style?: CSSProperties }) {
   return <div className={cn('bg-bg-inset rounded-sm animate-pulse', className)} style={style} />
 }

package/src/Toast.tsx

@@ -153,6 +153,9 @@ const ToastContext = createContext<ToastValue | null>(null)
 /** D7: three on screen at once. */
 const VISIBLE_TOASTS = 3
 
+/** Mount once, near the top of an app. It owns the stack, the timers and the
+ *  portal every toast goes through, and it is what `useToast` talks to. Three
+ *  show at once; a fourth waits for one of them to close. */
 export function ToastProvider({ children }: { children: ReactNode }) {
   // One manager per provider, so `useToast` can add and close without
   // re-rendering every caller each time the list changes.
@@ -227,6 +230,8 @@ function ToastList() {
   })
 }
 
+/** How anything under a `ToastProvider` raises a toast (`showToast`) or takes
+ *  one away (`dismissToast`). Throws outside a provider. */
 export function useToast(): ToastValue {
   const ctx = useContext(ToastContext)
   if (!ctx) throw new Error('useToast must be used within ToastProvider')

package/src/Toolbar.tsx

@@ -104,6 +104,8 @@ export interface ToolbarButtonProps extends IconButtonProps {
   ref?: Ref<HTMLButtonElement>
 }
 
+/** An `IconButton` that is an item of a `Toolbar`: the arrow keys reach it, and
+ *  a disabled one stays in the walk so its reason can still be read. */
 export function ToolbarButton({ ref, disabled, disabledReason, ...props }: ToolbarButtonProps) {
   return (
     <BaseToolbar.Button
@@ -137,6 +139,8 @@ export function ToolbarButton({ ref, disabled, disabledReason, ...props }: Toolb
  */
 export type ToolbarInputProps = TextInputProps
 
+/** A `TextInput` that is an item of a `Toolbar`, so the arrow keys walk into the
+ *  field and out of it again. */
 export function ToolbarInput({ size, ...props }: ToolbarInputProps) {
   // `size` is TextInput's own (default or small), not the native attribute
   // Base UI's part would take, so it goes to the field it draws.

package/src/Tooltip.tsx

@@ -146,6 +146,10 @@ function TooltipSurface({ label, shortcut, placement }: { label: string; shortcu
   )
 }
 
+/** A tooltip on something that cannot be its own trigger — a span, a `Chip`,
+ *  an icon. It wraps what it is given in an element that carries the handlers.
+ *  A control that can be the trigger does it itself: `IconButton` takes a
+ *  `tooltip` prop, and `Button` shows a `disabledReason` the same way. */
 export function WithTooltip({ label, shortcut, placement = 'top', wrapperClassName, children }: WithTooltipProps) {
   return (
     <BaseTooltip.Root disableHoverablePopup>