Blocks / Display menu

Display menu

How a view shows: its layouts, grouping, ordering, switches, properties. Built from props, or composed from parts.

import { DisplayMenu, DisplayLayouts, DisplaySelect, DisplayToggle, DisplayProperties, DisplaySection, DisplayWhen, DisplayReset, MORE_LAYOUTS, type DisplayOptions } from "@forgeron/ui";
/01 → Default
import { DisplayMenu, type DisplayOptions } from "@forgeron/ui";
import { useState } from "react";

const initial: DisplayOptions = {
  layout: "list",
  grouping: "status",
  ordering: "priority",
  toggles: { subIssues: true, emptyGroups: false },
  properties: ["id", "status", "priority", "labels", "assignee"],
};

export default function Default() {
  const [display, setDisplay] = useState(initial);
  return (
    <DisplayMenu
      value={display}
      onChange={setDisplay}
      defaultValue={initial}
      groupings={[
        { value: "status", label: "Status" },
        { value: "assignee", label: "Assignee" },
        { value: "project", label: "Project" },
        { value: "priority", label: "Priority" },
        { value: "none", label: "No grouping" },
      ]}
      orderings={[
        { value: "priority", label: "Priority" },
        { value: "due", label: "Due date" },
        { value: "created", label: "Created" },
        { value: "updated", label: "Updated" },
      ]}
      toggles={[
        { id: "subIssues", label: "Show sub-issues" },
        { id: "emptyGroups", label: "Show empty groups" },
      ]}
      properties={[
        { id: "id", label: "ID" },
        { id: "status", label: "Status" },
        { id: "priority", label: "Priority" },
        { id: "labels", label: "Labels" },
        { id: "project", label: "Project" },
        { id: "due", label: "Due date" },
        { id: "assignee", label: "Assignee" },
      ]}
    />
  );
}
/02 → Applied
{
  "layout": "board",
  "grouping": "assignee",
  "ordering": "due",
  "toggles": {
    "emptyGroups": true
  },
  "properties": [
    "id",
    "due"
  ]
}
import { Calendar03Icon, Folder01Icon, Loading03Icon, UserIcon } from "@forgeron/icons";
import { DisplayMenu, type DisplayOptions } from "@forgeron/ui";
import { useState } from "react";

const initial: DisplayOptions = {
  layout: "board",
  grouping: "assignee",
  ordering: "due",
  toggles: { emptyGroups: true },
  properties: ["id", "due"],
};

export default function Applied() {
  const [display, setDisplay] = useState(initial);
  return (
    <div style={{ width: "100%", display: "grid", gap: 12 }}>
      <div style={{ display: "flex", justifyContent: "flex-end" }}>
        <DisplayMenu
          value={display}
          onChange={setDisplay}
          groupings={[
            { value: "status", label: "Status", icon: Loading03Icon },
            { value: "assignee", label: "Assignee", icon: UserIcon },
            { value: "project", label: "Project", icon: Folder01Icon },
            { value: "none", label: "No grouping" },
          ]}
          orderings={[
            { value: "priority", label: "Priority" },
            { value: "due", label: "Due date", icon: Calendar03Icon },
            { value: "updated", label: "Updated" },
          ]}
          toggles={[{ id: "emptyGroups", label: "Show empty groups" }]}
          properties={[
            { id: "id", label: "ID" },
            { id: "status", label: "Status" },
            { id: "due", label: "Due date" },
            { id: "assignee", label: "Assignee" },
          ]}
        />
      </div>
      <pre
        style={{
          margin: 0,
          padding: 12,
          border: "1px solid var(--line)",
          color: "var(--ink-muted)",
          font: "400 12px/18px var(--font-mono)",
        }}
      >
        {JSON.stringify(display, null, 2)}
      </pre>
    </div>
  );
}
/03 → Composed
timeline · zoom weeks · milestones on
// Composed from parts: a Timeline layout added after List and Board, with a Zoom choice that only
// shows for it, kept in `options.zoom`.
import { ChartGanttIcon } from "@forgeron/icons";
import {
  DEFAULT_LAYOUTS,
  DisplayLayouts,
  DisplayMenu,
  DisplayProperties,
  DisplayReset,
  DisplaySection,
  DisplaySelect,
  DisplayToggle,
  DisplayWhen,
  type DisplayOptions,
} from "@forgeron/ui";
import { useState } from "react";

const initial: DisplayOptions = {
  layout: "timeline",
  grouping: "project",
  ordering: "due",
  toggles: { milestones: true },
  properties: ["id", "assignee"],
  options: { zoom: "weeks" },
};

export default function Composed() {
  const [display, setDisplay] = useState(initial);
  return (
    <div style={{ display: "grid", gap: 12, justifyItems: "start" }}>
      <DisplayMenu value={display} onChange={setDisplay} defaultValue={initial}>
        <DisplayLayouts
          layouts={[
            ...DEFAULT_LAYOUTS,
            { value: "timeline", label: "Timeline", icon: ChartGanttIcon },
          ]}
        />
        <DisplaySelect
          name="grouping"
          label="Grouping"
          options={[
            { value: "project", label: "Project" },
            { value: "assignee", label: "Assignee" },
            { value: "none", label: "No grouping" },
          ]}
        />
        <DisplaySelect
          name="ordering"
          label="Ordering"
          options={[
            { value: "due", label: "Due date" },
            { value: "priority", label: "Priority" },
          ]}
        />
        <DisplayWhen layout="timeline">
          <DisplaySection title="Timeline">
            <DisplaySelect
              name="zoom"
              label="Zoom"
              options={[
                { value: "weeks", label: "Weeks" },
                { value: "months", label: "Months" },
                { value: "quarters", label: "Quarters" },
              ]}
            />
            <DisplayToggle id="milestones" label="Show milestones" />
          </DisplaySection>
        </DisplayWhen>
        <DisplayWhen layout={["list", "board"]}>
          <DisplayProperties
            properties={[
              { id: "id", label: "ID" },
              { id: "status", label: "Status" },
              { id: "assignee", label: "Assignee" },
            ]}
          />
        </DisplayWhen>
        <DisplayReset />
      </DisplayMenu>
      <code className="t-mono" style={{ color: "var(--ink-muted)", fontSize: 12 }}>
        {display.layout} · zoom {display.options?.zoom} · milestones{" "}
        {display.toggles.milestones ? "on" : "off"}
      </code>
    </div>
  );
}
API → Props
PropTypeDefaultDescription
valueDisplayOptions—{ layout, grouping, ordering, toggles: Record<id, boolean>, properties: id[], options?: Record<name, string> }.
onChange(value: DisplayOptions) => void—Called on every change; changes apply at once.
childrenReactNode—The parts, in any order: DisplayLayouts, DisplaySelect (grouping, ordering, or any name kept in options), DisplayToggle, DisplayProperties, DisplaySection, DisplayWhen layout=…, DisplayReset. Without children the props below build the usual menu.
open / onOpenChangeboolean / (open) => void—Opens the menu from outside, e.g. from the V shortcut (useDisclosure).
groupingsSelectMenuOption[]—The ways to group rows: Status, Assignee, No grouping.
orderingsSelectMenuOption[]—The ways to order rows: Priority, Due date, Updated.
toggles{ id, label }[][]Switches such as Show sub-issues, Show empty groups.
properties{ id, label }[][]The properties a row can show, toggled as chips.
layouts{ value, label, icon?, kbd? }[]List, BoardThe layout switch; [] hides it.
defaultValueDisplayOptions—Offers Reset to default when the value differs from it.
labelstring"Display"The words of the button.
classNamestring—Extra classes.