Document Alert, Card, Switch and Text

Author: jviide

src/ui/experimental/Alert.ts

@@ -1,11 +1,36 @@
 import { UiNode, element } from "../internal.js";
 
 type AlertProps = {
+  /**
+   * The type of alert. Affects e.g. its visual styling.
+   * Default value: "info".
+   */
   type?: "info" | "success" | "warning" | "error";
+  /**
+   * A title or heading for the alert.
+   * Optional, but recommended for providing a concise summary of the alert's content.
+   */
   title?: string;
+  /**
+   * The main content of the alert. This can be text or more complex UI elements.
+   */
   children?: UiNode;
 };
 
+/**
+ * A component for displaying an alert message to the user.
+ *
+ * Alerts can be used to communicate errors and warnings, but also
+ * general feedback like acknowledgements for successful actions
+ * or neutral informational messages.
+ *
+ * @example
+ * ```tsx
+ * <Alert type="error" title="Something went wrong">
+ *   An error occurred while processing your request.
+ * </Alert>
+ * ```
+ * */
 export function Alert(props: AlertProps): UiNode {
   return element("ui-alert", props);
 }

src/ui/experimental/Card.ts

@@ -1,9 +1,26 @@
 import { UiNode, element } from "../internal.js";
 
 type CardProps = {
+  /**
+   * The content to be displayed inside the card.
+   * Can include text or other UI components.
+   */
   children?: UiNode;
 };
 
+/**
+ * A card-like container.
+ *
+ * Can hold various types of content. Often used to group related
+ * information.
+ *
+ * @example
+ * ```tsx
+ * <Card>
+ *   Hello, World!
+ * </Card>
+ * ```
+ * */
 export function Card(props: CardProps): UiNode {
   return element("ui-card", props);
 }

src/ui/experimental/Switch.ts

@@ -1,13 +1,66 @@
 import { Json, UiNode, element } from "../internal.js";
 
 type SwitchProps = {
+  /**
+   * An optional name for the switch input element.
+   *
+   * Used as the name for the switch value when client state is submitted
+   * to the UI endpoint. The value is send as a boolean (on as `true`,
+   * off as `false`).
+   *
+   * When not defined, the switch value is not sent as a part of client state.
+   */
   name?: string;
+  /**
+   * The text label associated with the switch.
+   * Improves usability and accessibility by providing context for the switch.
+   */
   label?: string;
+  /**
+   * If defined (i.e. not `undefined`), toggling the switch submits the `action`
+   * value with client input state to the UI endpoint.
+   */
   action?: Json;
+  /**
+   * Determines whether the switch is in the on (true) or off (false) state.
+   * Default value: false.
+   */
   checked?: boolean;
+  /**
+   * If true, the switch will be uninteractable and visually indicate
+   * its disabled state.
+   * Default value: false.
+   */
   disabled?: boolean;
 };
 
+/**
+ * A component that renders a toggle switch control.
+ * Switches are used for binary choices, typically to turn a specific
+ * feature or option on or off.
+ *
+ * @example
+ * ```tsx
+ * <Switch
+ *   name="notifications"
+ *   label="Enable notifications"
+ *   checked={true}
+ * />
+ * ```
+ *
+ * @example
+ * When the `action` property is defined, its value is immediately
+ * submitted to the UI endpoint when the switch is toggled. The surrounding
+ * client input data is sent along with the action.
+ *
+ * ```tsx
+ * <Switch
+ *   label="Enable notifications"
+ *   checked={true}
+ *   action={{ notifications: true }}
+ * />
+ * ```
+ * */
 export function Switch(props: SwitchProps): UiNode {
   return element("ui-switch", props);
 }

src/ui/experimental/Text.ts

@@ -1,14 +1,62 @@
 import { Responsive, UiNode, element } from "../internal.js";
 
 type TextProps = {
+  /**
+   * Size of the text. Can be responsive.
+   * Inherited from surrounding context if not explicitly set.
+   */
   size?: Responsive<"xs" | "sm" | "md" | "lg">;
+  /**
+   * Horizontal text alignment. Can be responsive.
+   * Inherited from surrounding context if not explicitly set.
+   */
   align?: Responsive<"left" | "center" | "right">;
+  /**
+   * Font weight of the text. Can be responsive.
+   * Inherited from surrounding context if not explicitly set.
+   */
   weight?: Responsive<"regular" | "medium" | "semibold">;
+  /**
+   * Accent color of the text.
+   * Inherited from surrounding context if not explicitly set.
+   */
   color?: "base" | "gray" | "red" | "orange" | "yellow" | "green" | "blue";
+  /**
+   * If true, the text will be truncated with an ellipsis if it exceeds
+   * the width of its container.
+   * Default value: false.
+   */
   truncate?: boolean;
+  /**
+   * The content to be displayed. Can be a string or more complex UI elements.
+   */
   children?: UiNode;
 };
 
+/**
+ * A component for rendering text with various styling options.
+ * Provides control over e.g. size, alignment, weight, color, and truncation
+ * of text.
+ *
+ * @example
+ * ```tsx
+ * <Text size="lg" weight="semibold" color="blue">
+ *   This is a large, semibold, blue text.
+ * </Text>
+ * ```
+ *
+ * When not explicitly set, most properties inherit their values from the
+ * surrounding context.
+ *
+ * @example
+ * ```tsx
+ * <Text color="semibold">
+ *   <Text weight="red">
+ *     This is a semibold, red text.
+ *   </Text>
+ * <Text>
+ * ```
+ * */
 export function Text(props: TextProps): UiNode {
   return element("ui-text", props);
 }