Mixins / foldkit-mixins-ui

Toolbar

namespace · packages/mixins-ui/src/toolbar.ts:1

export * as Toolbar from './toolbar.js'

In the guides

Members

Toolbar.configure

function · packages/mixins-ui/src/toolbar.ts:148

function configure<const Names extends string = never>(
  config: Presets<ToolbarPreset, Names>,
): {
  readonly view: <Outer>(
    options: ToolbarView<Outer> & PresetOption<Names>,
    h: HtmlBuilder<Outer>,
  ) => Html
}

The application's own Toolbar: base for every use, presets chosen at a use with preset, and the call over both. mixins concatenate in that order; a style given at the call replaces the preset's.

Toolbar.conflict

function · packages/mixins-ui/src/toolbar.ts:214

function conflict<Message>(
  routes: ReadonlyArray<Behaviors.Keys.Route<undefined, Message>>,
  input?: Pick<ToolbarView<Message>, 'orientation'>,
): Option.Option<Diagnostic>

The mixins:key-conflict that drawing the toolbar with routes would throw, or none: the application's routes against the arrows along the orientation (default 'horizontal'), Home and End, and against each other. A disabled toolbar still builds its routes, so it throws as well.

Toolbar.controlId

function · packages/mixins-ui/src/toolbar.ts:160

function controlId(toolbarId: string, id: string): string

The id the control id of the toolbar toolbarId draws, for a Command that focuses it.

Toolbar.focused

function · packages/mixins-ui/src/toolbar.ts:132

function focused<Message>(
  wrap: (message: RovingTabindex.Message) => Message,
): (id: string) => Message

onFocus for a toolbar whose tab stop is Bundles.Toolbar: the Focused Message of the stop, wrapped as the application wraps that child's Messages.

Toolbar.ToolbarControl

interface · packages/mixins-ui/src/toolbar.ts:75

interface ToolbarControl<Message> {
  readonly id: string
  readonly disabled?: boolean | undefined
  readonly draw: (stop: ToolbarStop<Message>) => Html
}

One focusable element, drawn by the application.

Toolbar.ToolbarGroup

interface · packages/mixins-ui/src/toolbar.ts:83

interface ToolbarGroup<Message> {
  readonly label: string
  readonly controls: ReadonlyArray<ToolbarControl<Message>>
  readonly disabled?: boolean | undefined
}

Controls under a name, as role="group".

Toolbar.ToolbarItem

type · packages/mixins-ui/src/toolbar.ts:92

type ToolbarItem<Message> =
  ToolbarControl<Message> | ToolbarGroup<Message> | 'separator'

What a toolbar holds, in order: a control, a named group of controls, or 'separator', a rule between sets.

Toolbar.ToolbarPattern

const · packages/mixins-ui/src/toolbar.ts:44

const ToolbarPattern: A11y.Pattern<{
  readonly root: {
    readonly capability: Capability.Capability<
      'Container',
      readonly [
        Capability.Capability<
          'Interactive',
          readonly [Capability.Capability<'Base', readonly []>]
        >,
      ]
    >
    readonly events: readonly [Event.EventToken<'keydown'>]
    readonly attributes: readonly [
      Attr.AttrToken<'role'>,
      Attr.AttrToken<'aria-label'>,
    ]
    readonly obligations: readonly [
      A11y.Obligation<'navigation'>,
      A11y.Obligation<'focus-strategy'>,
      A11y.Obligation<'name'>,
    ]
  }
  readonly group: {
    readonly capability: Capability.Capability<
      'Container',
      readonly [
        Capability.Capability<
          'Interactive',
          readonly [Capability.Capability<'Base', readonly []>]
        >,
      ]
    >
    readonly attributes: readonly [
      Attr.AttrToken<'role'>,
      Attr.AttrToken<'aria-label'>,
    ]
    readonly optional: true
  }
  readonly separator: {
    readonly capability: Capability.Capability<
      'Container',
      readonly [
        Capability.Capability<
          'Interactive',
          readonly [Capability.Capability<'Base', readonly []>]
        >,
      ]
    >
    readonly attributes: readonly [Attr.AttrToken<'role'>]
    readonly optional: true
  }
}>

The toolbar's own contract: a named, keyboard-navigable root. Its controls are the caller's, so their roles and activation are theirs; the group and separator carry only a role.

Toolbar.ToolbarPreset

type · packages/mixins-ui/src/toolbar.ts:138

type ToolbarPreset = Pick<
  ToolbarView<never>,
  'orientation' | 'direction' | 'loop' | 'style'
> & {
  readonly mixins?: MixinList<never>
}

What a Toolbar is given once: its look and each option that holds no Message, state or drawing.

Toolbar.ToolbarSlots

const · packages/mixins-ui/src/toolbar.ts:26

const ToolbarSlots: Slots.Contract<{
  readonly root: Slot.UnnamedSlot<
    Capability.Capability<
      'Container',
      readonly [
        Capability.Capability<
          'Interactive',
          readonly [Capability.Capability<'Base', readonly []>]
        >,
      ]
    >,
    readonly [Event.EventToken<'keydown'>],
    readonly [
      Attr.AttrToken<'role'>,
      Attr.AttrToken<'aria-label'>,
      Attr.AttrToken<'aria-disabled'>,
    ],
    readonly Slot.RequirementName[],
    boolean
  >
  readonly group: Slot.UnnamedSlot<
    Capability.Capability<
      'Container',
      readonly [
        Capability.Capability<
          'Interactive',
          readonly [Capability.Capability<'Base', readonly []>]
        >,
      ]
    >,
    readonly Slot.EventName[],
    readonly [Attr.AttrToken<'role'>, Attr.AttrToken<'aria-label'>],
    readonly Slot.RequirementName[],
    boolean
  >
  readonly separator: Slot.UnnamedSlot<
    Capability.Capability<
      'Container',
      readonly [
        Capability.Capability<
          'Interactive',
          readonly [Capability.Capability<'Base', readonly []>]
        >,
      ]
    >,
    readonly Slot.EventName[],
    readonly [Attr.AttrToken<'role'>],
    readonly Slot.RequirementName[],
    boolean
  >
}>

A toolbar publishes its root, the groups that gather related controls under a name, and the separator between sets. The controls are the caller's own elements (a Button, a toggle, a menu's trigger), which the toolbar hands the attributes of its one tab stop; it adds no markup around them, so a control keeps the class of its own recipe.

Toolbar.ToolbarStop

interface · packages/mixins-ui/src/toolbar.ts:60

interface ToolbarStop<Message> {
  readonly attributes: ReadonlyArray<Attribute<Message>>
  readonly disabled: boolean
}

What a control's draw receives to put on its one focusable element.

Toolbar.ToolbarView

interface · packages/mixins-ui/src/toolbar.ts:94

interface ToolbarView<Message> {
  readonly id: string
  readonly label: string
  readonly items: ReadonlyArray<ToolbarItem<Message>>
  readonly roving: RovingTabindex.Model
  readonly onFocus: (id: string) => NoInfer<Message>
  readonly orientation?: 'horizontal' | 'vertical' | undefined
  readonly direction?: 'ltr' | 'rtl' | undefined
  readonly loop?: boolean | undefined
  readonly disabled?: boolean | undefined
  readonly routes?:
    ReadonlyArray<Behaviors.Keys.Route<undefined, NoInfer<Message>>> | undefined
  readonly style?: NamedStyle<typeof ToolbarSlots> | undefined
  readonly mixins?: MixinList<Message> | undefined
}

Toolbar.view

function · packages/mixins-ui/src/toolbar.ts:239

function view<Message>(
  options: ToolbarView<Message>,
  h: HtmlBuilder<Message>,
): Html

A toolbar in one call, the APG's: role="toolbar" named by label, one tab stop over its controls, and the arrows along the orientation, Home and End moving focus between them. The view holds no state; the application keeps the tab stop (roving, a placed RovingTabindex) so that leaving and coming back with Tab lands on the control focused last.

A disabled control is skipped by the arrows and takes no focus, as in Segmented: the APG leaves the choice open, and a focusable disabled control would stop a keyboard user on something that does nothing. A text field, a select or a range keeps the keys it uses itself (see usedBy), so the arrows leave a text field only from the edge they point at, and Home and End never leave it: place a field last, as the APG advises, or leave it with Tab. A press that starts in something the toolbar did not draw (a menu's items) is left to it.