@wistia/ui 0.21.1 → 0.21.2-beta.527f4090.c8c7b4e

package/dist/index.d.ts

@@ -351,6 +351,8 @@ type BaseButtonProps = {
     rightIcon?: ReactNode | undefined;
     /**
      * The size of button to display. Can be used as a [responsive prop](/docs/ui-docs-responsive-props--docs)
+     *
+     * @type ResponsiveObject<'lg' | 'md' | 'sm' | 'xl'>
      */
     size?: ButtonSizes | ResponsiveObject<ButtonSizes>;
     /**
@@ -614,11 +616,11 @@ declare const Avatar: {
 type BadgeVariants = 'default' | 'outline';
 type BadgeProps = ComponentPropsWithoutRef<'div'> & {
     /**
-     * Sets the [color scheme](../?path=/docs/docs-color-schemes--docs)
+     * Sets the [color scheme](/docs/color-schemes)
      */
     colorScheme?: ColorSchemeTypes;
     /**
-     * Optional `Icon` component to use. Must be an instance of [Icon](../?path=/docs/components-icon--docs)
+     * Optional `Icon` component to use. Must be an instance of [Icon](/docs/components/Icon)
      */
     icon?: JSX.Element | undefined;
     /**
@@ -635,11 +637,11 @@ type BadgeProps = ComponentPropsWithoutRef<'div'> & {
  */
 declare const Badge: react.ForwardRefExoticComponent<Omit<react.DetailedHTMLProps<react.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & {
     /**
-     * Sets the [color scheme](../?path=/docs/docs-color-schemes--docs)
+     * Sets the [color scheme](/docs/color-schemes)
      */
     colorScheme?: ColorSchemeTypes;
     /**
-     * Optional `Icon` component to use. Must be an instance of [Icon](../?path=/docs/components-icon--docs)
+     * Optional `Icon` component to use. Must be an instance of [Icon](/docs/components/Icon)
      */
     icon?: JSX.Element | undefined;
     /**
@@ -750,7 +752,8 @@ type BoxProps = ComponentPropsWithoutRef<typeof DEFAULT_ELEMENT$1> & {
     /**
      * Specifies how the browser distributes space between and around
      * items along the cross-axis of their container; has no effect on
-     * single line flexible boxes. Can be a [responsive prop](/docs/ui-docs-responsive-props--docs).
+     * single line flexible boxes. Can be a [responsive prop](/docs/responsive-props).
+     * @type ResponsiveObject<"center" | "flex-end" | "flex-start" | "space-around" | "space-between" | "stretch">
      */
     alignContent?: AlignContentType | ResponsiveObject<AlignContentType>;
     /**
@@ -759,23 +762,28 @@ type BoxProps = ComponentPropsWithoutRef<typeof DEFAULT_ELEMENT$1> & {
      * to the alignContent prop is that alignItems specifies the
      * alignment of the items within the current container's line,
      * whereas alignContent specifies the alignment of the lines themselves.
-     * Can be a [responsive prop](/docs/ui-docs-responsive-props--docs).
+     * Can be a [responsive prop](/docs/responsive-props).
+     * @type ResponsiveObject<"baseline" | "center" | "flex-end" | "flex-start" | "stretch">
      */
     alignItems?: AlignItemsType | ResponsiveObject<AlignItemsType>;
     /**
      * Specifies how the browser aligns items of the current line, overriding the
      * alignItems value of parent; if any of the item's cross-axis margin is set to auto,
-     * then alignSelf is ignored. Can be a [responsive prop](/docs/ui-docs-responsive-props--docs).
+     * then alignSelf is ignored. Can be a [responsive prop](/docs/responsive-props).
      *
      * *Note: only works for nested `<Box />`*
+     *
+     * @type ResponsiveObject<'auto' | 'baseline' | 'center' | 'flex-end' | 'flex-start' | 'stretch'>
      */
     alignSelf?: AlignSelfType | ResponsiveObject<AlignSelfType>;
     /**
-     * Specifies the initial main size of an item. Can be a [responsive prop](/docs/ui-docs-responsive-props--docs).
+     * Specifies the initial main size of an item. Can be a [responsive prop](/docs/responsive-props).
      *
      * *Note: Cannot be used with `flexMode` prop.*
      *
      * *Note: only works for nested `<Box />`*
+     * @type ResponsiveObject<'string'>
+  
      */
     basis?: ResponsiveObject<string> | string;
     /**
@@ -783,17 +791,19 @@ type BoxProps = ComponentPropsWithoutRef<typeof DEFAULT_ELEMENT$1> & {
      */
     children?: ReactNode;
     /**
-     * Specifies the main axis of the container. Can be a [responsive prop](/docs/ui-docs-responsive-props--docs).
+     * Specifies the main axis of the container. Can be a [responsive prop](/docs/responsive-props).
+     * @type ResponsiveObject<'column-reverse' | 'column' | 'row-reverse' | 'row'>
      */
     direction?: DirectionType | ResponsiveObject<DirectionType>;
     /**
      * Specifies whether the width and/or height should fill the container.
-     * Can be a [responsive prop](/docs/ui-docs-responsive-props--docs).
+     * Can be a [responsive prop](/docs/responsive-props).
      *
      * *Note: Cannot be used with height/width props when setting the corresponding dimension.*
      *
      * For example, `fill="vertical"` or `fill={true}` cannot be used with the `height` prop,
      * and `fill="horizontal"` or `fill={true}` cannot be used with the `width` prop.
+     * @type ResponsiveObject<boolean | 'horizontal' | 'vertical'>
      */
     fill?: FillType | ResponsiveObject<FillType>;
     /**
@@ -803,49 +813,58 @@ type BoxProps = ComponentPropsWithoutRef<typeof DEFAULT_ELEMENT$1> & {
      *
      * For example, `fillViewport="vertical"` or `fillViewport={true}` cannot be used with the `height` prop,
      * and `fillViewport="horizontal"` or `fillViewport={true}` cannot be used with the `width` prop.
+     * @type boolean | 'horizontal' | 'vertical'
      */
     fillViewport?: FillType;
     /**
-     * Predefined `flex` behavior patterns. Can be a [responsive prop](/docs/ui-docs-responsive-props--docs).
+     * Predefined `flex` behavior patterns. Can be a [responsive prop](/docs/responsive-props).
      *
      * - `grow`: fills available space (`flex: 1 0 0`)
      * - `initial`: default behavior (`flex: 0 1 auto`)
      * - `equal`: equal space distribution (`flex: 1`)
      * - `rigid`: fixed size (`flex: 0 0 auto`)
      * - `fluid`: responsive (`flex: 1 1 auto`)
+     *
+     * @type ResponsiveObject<'equal' | 'fluid' | 'grow' | 'initial' | 'rigid'>
      */
     flexMode?: FlexModeType | ResponsiveObject<FlexModeType>;
     /**
      * Specifies the gaps (gutters) between rows and columns.
-     * Can be a [responsive prop](/docs/ui-docs-responsive-props--docs).
+     * Can be a [responsive prop](/docs/responsive-props).
      *
      * Can be either a single spacing value that applies to both row and column gaps,
      * or an object specifying different values for row and column gaps.
+     *
+     * @type ResponsiveObject<Spacings | { row: Spacings; column: Spacings }>
      */
     gap?: Gap$1 | ResponsiveGap$1 | Spacings;
     /**
      * Specifies what amount of space inside the flex container the item should take up.
-     * Can be a [responsive prop](/docs/ui-docs-responsive-props--docs).
+     * Can be a [responsive prop](/docs/responsive-props).
      *
      * *Note: Cannot be used with `flexMode` prop.*
      *
      * *Note: only works for nested `<Box />`*
+     * @type ResponsiveObject<number | string>
      */
     grow?: ResponsiveObject<number | string> | number | string;
     /**
-     * Specifies the height of the box. Can be a [responsive prop](/docs/ui-docs-responsive-props--docs).
+     * Specifies the height of the box. Can be a [responsive prop](/docs/responsive-props).
      *
      * *Note: Cannot be used with fill="vertical" or fillViewport="vertical"*
+     * @type ResponsiveObject<string>
      */
     height?: ResponsiveObject<string> | string;
     /**
      * Make Layout behave like an inline element but still lay out its content according to flexbox model.
-     * Can be a [responsive prop](/docs/ui-docs-responsive-props--docs).
+     * Can be a [responsive prop](/docs/responsive-props).
+     * @type ResponsiveObject<boolean>
      */
     inline?: ResponsiveObject<boolean> | boolean;
     /**
      * Specifies how the browser distributes space between and around
-     * items along the main axis of their container. Can be a [responsive prop](/docs/ui-docs-responsive-props--docs).
+     * items along the main axis of their container. Can be a [responsive prop](/docs/responsive-props).
+     * @type ResponsiveObject<'center' | 'flex-end' | 'flex-start' | 'space-around' | 'space-between' | 'space-evenly'>
      */
     justifyContent?: JustifyContentType | ResponsiveObject<JustifyContentType>;
     /**
@@ -859,22 +878,25 @@ type BoxProps = ComponentPropsWithoutRef<typeof DEFAULT_ELEMENT$1> & {
     renderAs?: ElementType;
     /**
      * Specifies how items will shrink inside the container when the default size of
-     * items is larger than their container. Can be a [responsive prop](/docs/ui-docs-responsive-props--docs).
+     * items is larger than their container. Can be a [responsive prop](/docs/responsive-props).
      *
      * *Note: Cannot be used with `flexMode` prop.*
      *
      * *Note: only works for nested `<Box />`*
+     * @type ResponsiveObject<number>
      */
     shrink?: ResponsiveObject<number> | number;
     /**
      * Specifies whether items are forced into a single line or can be wrapped onto multiple lines.
-     * Can be a [responsive prop](/docs/ui-docs-responsive-props--docs).
+     * Can be a [responsive prop](/docs/responsive-props).
+     * @type ResponsiveObject<boolean>
      */
     wrapItems?: ResponsiveObject<boolean> | boolean;
     /**
-     * Specifies the width of the box. Can be a [responsive prop](/docs/ui-docs-responsive-props--docs).
+     * Specifies the width of the box. Can be a [responsive prop](/docs/responsive-props).
      *
      * *Note: Cannot be used with fill="horizontal" or fillViewport="horizontal"*
+     * @type ResponsiveObject<string>
      */
     width?: ResponsiveObject<string> | string;
 };
@@ -935,6 +957,8 @@ type ButtonGroupProps = ComponentPropsWithoutRef<'div'> & {
     collapseOnSmallScreens?: boolean;
     /**
      * The size of the buttons in the group. Setting this will override the size of any UI button passed in as a child.
+     *
+     * @type ResponsiveObject<'lg' | 'md' | 'sm' | 'xl' | 'natural'>
      */
     buttonSize?: ButtonGroupButtonSize | ResponsiveObject<ButtonGroupButtonSize>;
 };
@@ -1488,6 +1512,10 @@ declare const CollapsibleContent: ({ clamp, children }: CollapsibleContentProps)
 type ColorGridProps = PropsWithChildren & {
     label?: string;
 };
+/**
+ * Displays color options as a wrapped grid of swatches. Use `ColorGridOption`
+ * as children and pass an optional `label` for a heading.
+ */
 declare const ColorGrid: {
     ({ children, label }: ColorGridProps): JSX.Element;
     displayName: string;
@@ -1505,12 +1533,21 @@ type ColorPickerOption = {
 };
 
 type ColorGridOptionProps = ColorPickerOption;
+/**
+ * A single selectable color swatch for use inside a `ColorGrid`. Renders as
+ * a radio item with a tooltip showing the color's name or hex code.
+ */
 declare const ColorGridOption: {
     ({ value: rawValue, name }: ColorGridOptionProps): JSX.Element;
     displayName: string;
 };
 
 type ColorListProps = PropsWithChildren;
+/**
+ * Displays color options as a vertical list of labeled rows. Use
+ * `ColorListGroup` to organize options into labeled sections, and
+ * `ColorListOption` for individual items.
+ */
 declare const ColorList: {
     ({ children }: ColorListProps): JSX.Element;
     displayName: string;
@@ -1519,12 +1556,19 @@ declare const ColorList: {
 type ColorListGroupProps = PropsWithChildren<{
     label: string;
 }>;
+/**
+ * Groups `ColorListOption` items under a labeled heading within a `ColorList`.
+ */
 declare const ColorListGroup: {
     ({ label, children }: ColorListGroupProps): JSX.Element;
     displayName: string;
 };
 
 type ColorListOptionProps = ColorPickerOption;
+/**
+ * A single selectable row for use inside a `ColorList`. Displays a color
+ * swatch alongside the color's name (if provided) or hex code.
+ */
 declare const ColorListOption: {
     ({ value: rawValue, name }: ColorListOptionProps): JSX.Element;
     displayName: string;
@@ -1553,10 +1597,13 @@ type ColorPickerProps = PropsWithChildren<{
     value: string;
 }>;
 /**
- * ColorPicker is a composable component that allows you to create a color
- * picker with various controls and options. Choose the parts you need, leave
- * out the ones you don't, and include any custom UI you need alongside its
- * subcomponents.
+ * A composable color picker built from low-level building blocks. Choose the
+ * parts you need, leave out the ones you don't, and include any custom UI
+ * alongside its subcomponents.
+ *
+ * For most use cases in the Wistia app, prefer the pre-composed ColorPicker
+ * at `~/components/ColorPicker`, which assembles these primitives with
+ * sensible defaults (brand colors, contrast controls, popover/inline modes).
  */
 declare const ColorPicker: {
     ({ children, colorForComparison, minimumContrastRatio, opacityForContrastCalculation, onValueChange, value, }: ColorPickerProps): JSX.Element;
@@ -1564,23 +1611,42 @@ declare const ColorPicker: {
 };
 
 type ColorPickerPopoverContentProps = PropsWithChildren;
+/**
+ * The popover panel that opens when the `ColorPickerTrigger` is activated.
+ * Use `ColorPickerSection` to organize content within it.
+ */
 declare const ColorPickerPopoverContent: {
     ({ children, }: ColorPickerPopoverContentProps): JSX.Element;
     displayName: string;
 };
 
 type ColorPickerSectionProps = PropsWithChildren;
+/**
+ * A padded section for grouping related controls within a
+ * `ColorPickerPopoverContent`. Provides consistent spacing between sections.
+ */
 declare const ColorPickerSection: {
     ({ children }: ColorPickerSectionProps): JSX.Element;
     displayName: string;
 };
 
 type ColorPickerTriggerProps = PropsWithChildren;
+/**
+ * The button that toggles the color picker popover open and closed. By default
+ * it renders a swatch and hex label for the current color; pass custom children
+ * to replace that content.
+ */
 declare const ColorPickerTrigger: react.ForwardRefExoticComponent<{
     children?: react.ReactNode | undefined;
 } & react.RefAttributes<HTMLButtonElement>>;
 
 type ContrastControlsProps = object;
+/**
+ * Displays a preview of the selected color against the comparison color, the
+ * WCAG contrast ratio, and a toggle switch for enforcing minimum contrast.
+ * Relies on `colorForComparison` and `minimumContrastRatio` set on the parent
+ * `ColorPicker`.
+ */
 declare const ContrastControls: {
     (props: ContrastControlsProps): JSX.Element;
     displayName: string;
@@ -1592,12 +1658,22 @@ type HexColorInputProps = {
      */
     autoFocus?: boolean;
 };
+/**
+ * A text input for entering hex color codes directly. Validates input to
+ * allow only hex characters, normalizes pasted values, and supports arrow-key
+ * nudging of saturation. Auto-focuses by default for quick paste workflows.
+ */
 declare const HexColorInput: {
     ({ autoFocus }: HexColorInputProps): JSX.Element;
     displayName: string;
 };
 
 type HueSliderProps = object;
+/**
+ * A horizontal slider for adjusting the hue of the current color, rendered
+ * over a spectrum gradient. The thumb color reflects the currently selected
+ * hue, saturation, and value.
+ */
 declare const HueSlider: {
     (props: HueSliderProps): JSX.Element;
     displayName: string;
@@ -1606,12 +1682,22 @@ declare const HueSlider: {
 type SaturationAndValuePickerProps = {
     dataTestId?: string;
 };
+/**
+ * A 2D picking area for adjusting saturation (x-axis) and brightness/value
+ * (y-axis) of the current color. Supports click, drag, and keyboard arrow
+ * navigation. When contrast enforcement is enabled, a contrast boundary curve
+ * is drawn on the canvas.
+ */
 declare const SaturationAndValuePicker: {
     ({ dataTestId, }: SaturationAndValuePickerProps): JSX.Element;
     displayName: string;
 };
 
 type ValueNameOrHexCodeProps = object;
+/**
+ * Displays the name of the current color (if it matches a known color name)
+ * or its hex code. Reads the current value from ColorPicker context.
+ */
 declare const ValueNameOrHexCode: {
     (props: ValueNameOrHexCodeProps): JSX.Element;
     displayName: string;
@@ -1625,6 +1711,10 @@ type ColorSwatchProps = PropsWithChildren<{
 }>;
 
 type ValueSwatchProps = Pick<ColorSwatchProps, 'diameterPx'>;
+/**
+ * Renders a circular color swatch filled with the current color from
+ * ColorPicker context. Accepts an optional `diameterPx` to control size.
+ */
 declare const ValueSwatch: {
     ({ diameterPx, }: ValueSwatchProps): JSX.Element;
     displayName: string;
@@ -2657,12 +2747,17 @@ type PreviewCardProps = ContentProps$1 & {
      */
     closeDelay?: number;
     colorScheme?: ColorSchemeTypes;
+    /**
+     * @ignore
+     * Force the preview card to be open without user interaction (for debugging and CI)
+     */
+    forceOpen?: boolean;
 };
 /**
  * Preview cards reveal content on hover. **Everything in the card must also exist at the destination**—never put information only in the preview. This pattern is for sighted-only, so treat the card as a preview, not a source of truth.
  */
 declare const PreviewCard: {
-    ({ children, trigger, maxWidth, maxHeight, unstyled, paddingSize, openDelay, closeDelay, colorScheme, ...props }: PreviewCardProps): JSX.Element;
+    ({ children, trigger, maxWidth, maxHeight, unstyled, paddingSize, openDelay, closeDelay, colorScheme, forceOpen, ...props }: PreviewCardProps): JSX.Element;
     displayName: string;
 };
 

package/dist/index.js

@@ -1,6 +1,6 @@
 
 /*
- * @license @wistia/ui v0.21.1
+ * @license @wistia/ui v0.21.2-beta.527f4090.c8c7b4e
  *
  * Copyright (c) 2024-2026, Wistia, Inc. and its affiliates.
  *
@@ -8053,7 +8053,7 @@ var iconSizeMap = {
   xxl: "48"
 };
 var iconInlineStyle = css18`
-  [data-wui-icon-inline] {
+  & > [data-wui-icon-inline] {
     --wui-icon-inline-size: 0.8em;
     --wui-icon-inline-offset: 0.05em;
     --wui-icon-vertical-align: none;
@@ -8153,6 +8153,7 @@ var StyledLink = styled5.a`
   display: inline-flex;
   align-items: baseline;
   gap: var(--wui-space-01);
+  ${iconInlineStyle}
 
   &:hover {
     text-decoration: ${({ $underline }) => $underline === "hover" || $underline === "always" ? "underline" : "none"};
@@ -16064,17 +16065,23 @@ var PreviewCard = ({
   openDelay = 700,
   closeDelay = 300,
   colorScheme = "inherit",
+  forceOpen,
   ...props
 }) => {
   const style = {
     "--wui-preview-card-max-width": maxWidth,
     "--wui-preview-card-max-height": maxHeight
   };
+  const rootProps = {};
+  if (forceOpen === true) {
+    rootProps.open = true;
+  }
   return /* @__PURE__ */ jsxs49(
     Root2,
     {
       closeDelay,
       openDelay,
+      ...rootProps,
       children: [
         /* @__PURE__ */ jsx313(Trigger2, { asChild: true, children: trigger }),
         /* @__PURE__ */ jsx313(Portal, { children: /* @__PURE__ */ jsx313(