@varialkit/editabletitle 0.1.0

package/docs.md

@@ -0,0 +1,51 @@
+# EditableTitle
+
+EditableTitle provides inline editing for short text labels such as document titles. It supports async saves, keyboard
+shortcuts, and optional read-only mode.
+
+## How to Use
+
+```tsx
+import { EditableTitle } from "@solara/editabletitle";
+
+export function Example() {
+  const handleSave = async (nextTitle: string) => {
+    await api.updateTitle(nextTitle);
+    return true;
+  };
+
+  return <EditableTitle title="Quarterly Report" onSave={handleSave} />;
+}
+```
+
+## Best Practices
+
+- Keep titles short so they remain scannable when not focused.
+- Return `false` from `onSave` to rollback on errors.
+- Use `readOnly` when the title should not be editable.
+
+## Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `title` | `string` | _Required_ | Current title text. |
+| `onSave` | `(newTitle: string) => Promise<boolean>` | _Required_ | Async save handler; return `true` to accept changes. |
+| `readOnly` | `boolean` | `false` | Prevent editing when true. |
+| `size` | `"xs" \| "sm" \| "base" \| "lg" \| "xl" \| "2xl" \| "3xl" \| "4xl" \| "5xl" \| "6xl"` | `"lg"` | Typography size. |
+| `weight` | `"normal" \| "medium" \| "semibold" \| "bold"` | | Font weight. |
+| `fullWidth` | `boolean` | `false` | When `true`, the component will take up the full width of its container. |
+| `iconLeft` | `SolaraIconName \| IconProps` | | Optional leading icon before the title. |
+| `className` | `string` | | Custom class name. |
+
+## Accessibility
+
+- The button uses a clear focus ring for keyboard navigation.
+- The input preserves the current title value and supports Enter/Escape actions.
+
+## Icons
+
+You can render a leading icon before the title. Icons inherit the title text color.
+
+```tsx
+<EditableTitle title="Project Alpha" onSave={handleSave} iconLeft="data_spreadsheet_search_24" />
+```

package/examples/index.tsx

@@ -0,0 +1,249 @@
+import React from "react";
+import type { ReactElement } from "react";
+import { iconNames } from "@solara/icons";
+import type { SolaraIconName } from "@solara/icons";
+import { EditableTitle } from "../src/EditableTitle";
+import type { EditableTitleSize, EditableTitleWeight } from "../src/EditableTitle.types";
+
+type StoryControlOption = {
+  label: string;
+  value: string;
+};
+
+type StoryControl = {
+  name: string;
+  label?: string;
+  type: "select" | "text" | "boolean" | "number";
+  options?: Array<string | StoryControlOption>;
+  min?: number;
+  max?: number;
+  step?: number;
+};
+
+type StoryDefinition = {
+  title: string;
+  description?: string;
+  render: (props: Record<string, unknown>) => ReactElement;
+  controls?: StoryControl[];
+  initialProps?: Record<string, unknown>;
+  showProps?: boolean;
+  applyPropsToPreview?: boolean;
+  code?: string;
+};
+
+const simulateSave = async (nextTitle: string) => {
+  await new Promise((resolve) => setTimeout(resolve, 350));
+  return Boolean(nextTitle);
+};
+
+export const stories: Record<string, StoryDefinition> = {
+  playground: {
+    title: "Playground",
+    description: "Edit the title inline and explore typography options.",
+    render: (props) => (
+      <EditableTitlePlayground
+        title={(props.title as string) ?? "Project Alpha"}
+        size={props.size as EditableTitleSize}
+        weight={props.weight as EditableTitleWeight}
+        readOnly={props.readOnly as boolean}
+        fullWidth={props.fullWidth as boolean}
+        disabled={props.disabled as boolean}
+        iconLeft={(props.iconLeft as SolaraIconName) || undefined}
+      />
+    ),
+    controls: [
+      { name: "title", label: "Title", type: "text" },
+      {
+        name: "size",
+        label: "Size",
+        type: "select",
+        options: ["xs", "sm", "base", "lg", "xl", "2xl", "3xl"],
+      },
+      {
+        name: "weight",
+        label: "Weight",
+        type: "select",
+        options: ["normal", "medium", "semibold", "bold"],
+      },
+      { name: "readOnly", label: "Read Only", type: "boolean" },
+      { name: "fullWidth", label: "Full Width", type: "boolean" },
+      { name: "disabled", label: "Disabled", type: "boolean" },
+      {
+        name: "iconLeft",
+        label: "Icon Left",
+        type: "select",
+        options: ["", ...iconNames],
+      },
+    ],
+    initialProps: {
+      title: "Project Alpha",
+      size: "lg",
+      weight: "semibold",
+      readOnly: false,
+      fullWidth: false,
+      disabled: false,
+      iconLeft: "",
+    },
+  },
+  sizes: {
+    title: "Sizes",
+    showProps: false,
+    render: () => (
+      <div style={{ display: "grid", gap: "0.75rem" }}>
+        <EditableTitle title="Heading XS" onSave={simulateSave} size="xs" />
+        <EditableTitle title="Heading SM" onSave={simulateSave} size="sm" />
+        <EditableTitle title="Heading Base" onSave={simulateSave} size="base" />
+        <EditableTitle title="Heading LG" onSave={simulateSave} size="lg" />
+        <EditableTitle title="Heading XL" onSave={simulateSave} size="xl" />
+        <EditableTitle title="Heading 2XL" onSave={simulateSave} size="2xl" />
+      </div>
+    ),
+    code: `import { EditableTitle } from "@solara/editabletitle";
+
+const simulateSave = async (nextTitle: string) => {
+  await new Promise((resolve) => setTimeout(resolve, 350));
+  return Boolean(nextTitle);
+};
+
+export function Example() {
+  return (
+    <div style={{ display: "grid", gap: "0.75rem" }}>
+      <EditableTitle title="Heading XS" onSave={simulateSave} size="xs" />
+      <EditableTitle title="Heading SM" onSave={simulateSave} size="sm" />
+      <EditableTitle title="Heading Base" onSave={simulateSave} size="base" />
+      <EditableTitle title="Heading LG" onSave={simulateSave} size="lg" />
+      <EditableTitle title="Heading XL" onSave={simulateSave} size="xl" />
+      <EditableTitle title="Heading 2XL" onSave={simulateSave} size="2xl" />
+    </div>
+  );
+}
+`,
+  },
+  readonly: {
+    title: "Read Only",
+    showProps: false,
+    render: () => (
+      <EditableTitle
+        title="Read-only title"
+        onSave={simulateSave}
+        readOnly
+        weight="medium"
+      />
+    ),
+    code: `import { EditableTitle } from "@solara/editabletitle";
+
+const simulateSave = async (nextTitle: string) => {
+  await new Promise((resolve) => setTimeout(resolve, 350));
+  return Boolean(nextTitle);
+};
+
+export function Example() {
+  return (
+    <EditableTitle
+      title="Read-only title"
+      onSave={simulateSave}
+      readOnly
+      weight="medium"
+    />
+  );
+}
+`,
+  },
+  icons: {
+    title: "Icons",
+    showProps: false,
+    render: () => (
+      <div style={{ display: "grid", gap: "0.75rem" }}>
+        <EditableTitle title="Design systems" onSave={simulateSave} iconLeft="data_spreadsheet_search_24" />
+        <EditableTitle title="Launch plan" onSave={simulateSave} iconLeft="arrow_line_up_16" />
+      </div>
+    ),
+    code: `import { EditableTitle } from "@solara/editabletitle";
+
+const simulateSave = async (nextTitle: string) => {
+  await new Promise((resolve) => setTimeout(resolve, 350));
+  return Boolean(nextTitle);
+};
+
+export function Example() {
+  return (
+    <div style={{ display: "grid", gap: "0.75rem" }}>
+      <EditableTitle title="Design systems" onSave={simulateSave} iconLeft="data_spreadsheet_search_24" />
+      <EditableTitle title="Launch plan" onSave={simulateSave} iconLeft="arrow_line_up_16" />
+    </div>
+  );
+}
+`,
+  },
+  fullWidth: {
+    title: "Full Width",
+    showProps: false,
+    render: () => (
+      <div style={{ display: "grid", gap: "0.75rem", width: "400px" }}>
+        <EditableTitle title="This is a long title that should wrap" onSave={simulateSave} fullWidth />
+      </div>
+    ),
+    code: `import { EditableTitle } from "@solara/editabletitle";
+
+const simulateSave = async (nextTitle: string) => {
+  await new Promise((resolve) => setTimeout(resolve, 350));
+  return Boolean(nextTitle);
+};
+
+export function Example() {
+  return (
+    <div style={{ display: "grid", gap: "0.75rem", width: "400px" }}>
+      <EditableTitle title="This is a long title that should wrap" onSave={simulateSave} fullWidth />
+    </div>
+  );
+}
+`,
+  },
+};
+
+type EditableTitlePlaygroundProps = {
+  title: string;
+  size?: EditableTitleSize;
+  weight?: EditableTitleWeight;
+  readOnly?: boolean;
+  fullWidth?: boolean;
+  disabled?: boolean;
+  iconLeft?: SolaraIconName;
+};
+
+const EditableTitlePlayground = ({
+  title,
+  size,
+  weight,
+  readOnly,
+  fullWidth,
+  disabled,
+  iconLeft,
+}: EditableTitlePlaygroundProps) => {
+  const [currentTitle, setCurrentTitle] = React.useState(title);
+
+  React.useEffect(() => {
+    setCurrentTitle(title);
+  }, [title]);
+
+  const handleSave = async (nextTitle: string) => {
+    const ok = await simulateSave(nextTitle);
+    if (ok) {
+      setCurrentTitle(nextTitle);
+    }
+    return ok;
+  };
+
+  return (
+    <EditableTitle
+      title={currentTitle}
+      onSave={handleSave}
+      size={size}
+      weight={weight}
+      readOnly={readOnly}
+      fullWidth={fullWidth}
+      disabled={disabled}
+      iconLeft={iconLeft}
+    />
+  );
+};

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@varialkit/editabletitle",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./examples": "./examples/index.tsx"
+  },
+  "dependencies": {
+    "@varialkit/icons": "0.1.0"
+  },
+  "files": [
+    "src",
+    "docs.md",
+    "examples",
+    "examples.tsx"
+  ],
+  "peerDependencies": {
+    "react": "^19.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "19.0.10",
+    "react": "19.0.0"
+  }
+}

package/src/EditableTitle.scss

@@ -0,0 +1,193 @@
+.solara-editable-title {
+  --editable-title-font-size: var(--font-size-h5-scaled);
+  --editable-title-line-height: var(--line-height-heading-scaled);
+
+  position: relative;
+  display: inline-flex;
+  width: auto;
+  max-width: 100%;
+  color: var(--color-text-primary);
+  font-family: var(--font-body);
+}
+
+.solara-editable-title--full-width {
+  width: 100%;
+}
+
+.solara-editable-title__input,
+.solara-editable-title__button {
+  font-size: var(--editable-title-font-size);
+  line-height: var(--editable-title-line-height);
+}
+
+.solara-editable-title__input {
+  background: transparent;
+  border: none;
+  outline: none;
+  padding: calc(var(--space-1) * var(--spacing-multiplier))
+    calc(var(--space-2) * var(--spacing-multiplier));
+  margin: calc(var(--space-1) * -1 * var(--spacing-multiplier))
+    calc(var(--space-2) * -1 * var(--spacing-multiplier));
+  width: calc(100% + (var(--space-2) * 2 * var(--spacing-multiplier)));
+  transition: color 0.2s ease, background-color 0.2s ease;
+  color: inherit;
+  font-family: inherit;
+  display: block;
+  border-radius: var(--radius-2);
+
+  &::placeholder {
+    color: var(--color-text-secondary);
+  }
+}
+
+.solara-editable-title__button {
+  background: none;
+  border: none;
+  cursor: pointer;
+  text-align: left;
+  padding: calc(var(--space-1) * var(--spacing-multiplier))
+    calc(var(--space-2) * var(--spacing-multiplier));
+  margin: calc(var(--space-1) * -1 * var(--spacing-multiplier))
+    calc(var(--space-2) * -1 * var(--spacing-multiplier));
+  border-radius: var(--radius-2);
+  transition: background-color 0.2s ease, color 0.2s ease;
+  width: 100%;
+  color: inherit;
+  font-family: inherit;
+  display: inline-flex;
+  align-items: center;
+  gap: calc(var(--space-2) * var(--spacing-multiplier));
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+
+  &:hover:not(:disabled) {
+    background-color: var(--color-surface-100);
+  }
+
+  &:focus-visible {
+    outline: none;
+    box-shadow: 0 0 0 3px var(--color-focus-halo);
+  }
+
+  &:disabled {
+    cursor: default;
+    background-color: transparent;
+  }
+}
+
+.solara-editable-title__icon {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  color: currentColor;
+  flex-shrink: 0;
+}
+
+.solara-editable-title__icon .solara-icon [stroke]:not([stroke="none"]) {
+  stroke: currentColor;
+}
+
+.solara-editable-title__icon .solara-icon [fill]:not([fill="none"]) {
+  fill: currentColor;
+}
+
+.solara-editable-title__label {
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+
+
+.solara-editable-title__spinner {
+  position: absolute;
+  right: calc(var(--space-2) * var(--spacing-multiplier));
+  top: 50%;
+  width: calc(var(--space-3) * var(--spacing-multiplier));
+  height: calc(var(--space-3) * var(--spacing-multiplier));
+  border-radius: 999px;
+  border: 2px solid var(--color-divider-secondary);
+  border-top-color: var(--color-accent-primary);
+  transform: translateY(-50%);
+  animation: solara-editable-title-spin 1s linear infinite;
+}
+
+.solara-editable-title--size-xs {
+  --editable-title-font-size: var(--font-size-footnote-scaled);
+  --editable-title-line-height: var(--line-height-footnote-scaled);
+}
+
+.solara-editable-title--size-sm {
+  --editable-title-font-size: var(--font-size-caption-scaled);
+  --editable-title-line-height: var(--line-height-caption-scaled);
+}
+
+.solara-editable-title--size-base {
+  --editable-title-font-size: var(--font-size-body-scaled);
+  --editable-title-line-height: var(--line-height-body-scaled);
+}
+
+.solara-editable-title--size-lg {
+  --editable-title-font-size: var(--font-size-subhead-scaled);
+  --editable-title-line-height: var(--line-height-body-scaled);
+}
+
+.solara-editable-title--size-xl {
+  --editable-title-font-size: var(--font-size-h5-scaled);
+  --editable-title-line-height: var(--line-height-heading-scaled);
+}
+
+.solara-editable-title--size-2xl {
+  --editable-title-font-size: var(--font-size-h4-scaled);
+  --editable-title-line-height: var(--line-height-heading-scaled);
+}
+
+.solara-editable-title--size-3xl {
+  --editable-title-font-size: var(--font-size-h3-scaled);
+  --editable-title-line-height: var(--line-height-heading-scaled);
+}
+
+.solara-editable-title--size-4xl {
+  --editable-title-font-size: var(--font-size-h2-scaled);
+  --editable-title-line-height: var(--line-height-heading-scaled);
+}
+
+.solara-editable-title--size-5xl {
+  --editable-title-font-size: var(--font-size-h1-scaled);
+  --editable-title-line-height: var(--line-height-heading-scaled);
+}
+
+.solara-editable-title--size-6xl {
+  --editable-title-font-size: calc(var(--font-size-h1-scaled) * 1.125);
+  --editable-title-line-height: var(--line-height-heading-scaled);
+}
+
+.solara-editable-title--weight-normal .solara-editable-title__input,
+.solara-editable-title--weight-normal .solara-editable-title__button {
+  font-weight: 400;
+}
+
+.solara-editable-title--weight-medium .solara-editable-title__input,
+.solara-editable-title--weight-medium .solara-editable-title__button {
+  font-weight: 500;
+}
+
+.solara-editable-title--weight-semibold .solara-editable-title__input,
+.solara-editable-title--weight-semibold .solara-editable-title__button {
+  font-weight: 600;
+}
+
+.solara-editable-title--weight-bold .solara-editable-title__input,
+.solara-editable-title--weight-bold .solara-editable-title__button {
+  font-weight: 700;
+}
+
+@keyframes solara-editable-title-spin {
+  from {
+    transform: translateY(-50%) rotate(0deg);
+  }
+  to {
+    transform: translateY(-50%) rotate(360deg);
+  }
+}

package/src/EditableTitle.tsx

@@ -0,0 +1,140 @@
+import React, { forwardRef, useEffect, useRef, useState } from "react";
+import { Icon } from "@solara/icons";
+import type { IconProps } from "@solara/icons";
+import type { EditableTitleProps } from "./EditableTitle.types";
+import "./EditableTitle.scss";
+
+type EditableTitleIcon = IconProps | IconProps["name"];
+
+const normalizeIconProps = (icon: EditableTitleIcon): IconProps =>
+  typeof icon === "string" ? { name: icon } : icon;
+
+const resolveIconProps = (icon: EditableTitleIcon): IconProps => {
+  const iconProps = normalizeIconProps(icon);
+
+  return {
+    ...iconProps,
+    style: {
+      ...iconProps.style,
+      color: "currentColor",
+    },
+  };
+};
+
+export const EditableTitle = forwardRef<HTMLButtonElement, EditableTitleProps>(
+  (
+    {
+      title,
+      onSave,
+      className,
+      readOnly = false,
+      size = "lg",
+      weight,
+      fullWidth = false,
+      disabled,
+      iconLeft,
+      ...buttonProps
+    },
+    ref
+  ) => {
+    const [isEditing, setIsEditing] = useState(false);
+    const [isSaving, setIsSaving] = useState(false);
+    const [value, setValue] = useState(title);
+    const inputRef = useRef<HTMLInputElement>(null);
+
+    const isLocked = readOnly || Boolean(disabled);
+
+    useEffect(() => {
+      setValue(title);
+    }, [title]);
+
+    useEffect(() => {
+      if (isEditing && inputRef.current) {
+        inputRef.current.select();
+      }
+    }, [isEditing]);
+
+    const handleSave = async () => {
+      if (isLocked || isSaving) return;
+
+      const trimmedValue = value.trim();
+      if (!trimmedValue || trimmedValue === title) {
+        setValue(title);
+        setIsEditing(false);
+        return;
+      }
+
+      setIsSaving(true);
+      const success = await onSave(trimmedValue);
+      setIsSaving(false);
+
+      if (success) {
+        setIsEditing(false);
+      } else {
+        setValue(title);
+      }
+    };
+
+    const handleKeyDown = (event: React.KeyboardEvent<HTMLInputElement>) => {
+      if (event.key === "Enter") {
+        handleSave();
+      } else if (event.key === "Escape") {
+        setValue(title);
+        setIsEditing(false);
+      }
+    };
+
+    const rootClasses = [
+      "solara-editable-title",
+      size ? `solara-editable-title--size-${size}` : null,
+      weight ? `solara-editable-title--weight-${weight}` : null,
+      fullWidth ? "solara-editable-title--full-width" : null,
+      className,
+    ]
+      .filter(Boolean)
+      .join(" ");
+
+    if (isEditing) {
+      return (
+        <div className={rootClasses} aria-busy={isSaving}>
+          <input
+            ref={inputRef}
+            type="text"
+            value={value}
+            onChange={(event) => setValue(event.target.value)}
+            onKeyDown={handleKeyDown}
+            onBlur={handleSave}
+            className="solara-editable-title__input"
+            disabled={isSaving}
+            autoFocus
+          />
+          {isSaving ? (
+            <span className="solara-editable-title__spinner" aria-hidden="true" />
+          ) : null}
+        </div>
+      );
+    }
+
+    return (
+      <div className={rootClasses}>
+        <button
+          ref={ref}
+          type={buttonProps.type ?? "button"}
+          onClick={isLocked ? undefined : () => setIsEditing(true)}
+          className="solara-editable-title__button"
+          title={isLocked ? title : "Click to edit"}
+          disabled={isLocked}
+          {...buttonProps}>
+          {iconLeft ? (
+            <span className="solara-editable-title__icon" aria-hidden="true">
+              <Icon {...resolveIconProps(iconLeft)} />
+            </span>
+          ) : null}
+          <span className="solara-editable-title__label">{title}</span>
+        </button>
+      </div>
+    );
+  }
+);
+
+EditableTitle.displayName = "EditableTitle";

package/src/EditableTitle.types.ts

@@ -0,0 +1,36 @@
+import type React from "react";
+import type { IconProps } from "@solara/icons";
+
+export type EditableTitleSize =
+  | "xs"
+  | "sm"
+  | "base"
+  | "lg"
+  | "xl"
+  | "2xl"
+  | "3xl"
+  | "4xl"
+  | "5xl"
+  | "6xl";
+
+export type EditableTitleWeight = "normal" | "medium" | "semibold" | "bold";
+
+export interface EditableTitleProps
+  extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "title" | "onClick"> {
+  /** The title text displayed in view mode. */
+  title: string;
+  /** Called when the title is saved. Return true to accept the change. */
+  onSave: (newTitle: string) => Promise<boolean>;
+  /** Prevent editing when true. */
+  readOnly?: boolean;
+  /** Typography size token. */
+  size?: EditableTitleSize;
+  /** Typography weight token. */
+  weight?: EditableTitleWeight;
+  /** When true, the component will take up the full width of its container. */
+  fullWidth?: boolean;
+  /** Optional leading icon displayed before the title. */
+  iconLeft?: IconProps | IconProps["name"];
+  /** Additional class name. */
+  className?: string;
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export { EditableTitle } from "./EditableTitle";
+export type {
+  EditableTitleProps,
+  EditableTitleSize,
+  EditableTitleWeight,
+} from "./EditableTitle.types";