// Copyright 2026 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

// Braille display keyboard command.
enum KeyCommand {
  "line_up",
  "line_down",
  "pan_left",
  "pan_right",
  "top",
  "bottom",
  "routing",
  "secondary_routing",
  "dots",
  "chord",
  "standard_key"
};

// A keyboard event.  This is not a standard keyboard event because
// braille display keyboards look significantly different from standard
// keyboards.
dictionary KeyEvent {
  required KeyCommand command;
  // 0-based display position for commands that involve a routing key.
  long displayPosition;
  // Braille dot keys that were pressed, stored in the low-order bits.
  // Dot 1 is stored in bit 0, dot2 in bit 1, etc.
  long brailleDots;
  // DOM keyboard event code.  This is present when command is standard_key
  // and the braille display event represents a non-alphanumeric key such
  // as an arrow key or function key.
  // The value is as defined by the |code| property in
  // http://www.w3.org/TR/uievents/#keyboard-event-interface
  DOMString standardKeyCode;
  // DOM keyboard event character value.  This is present if the
  // braille key event corresponds to a character.
  DOMString standardKeyChar;
  // Whether the space key was pressed.
  boolean spaceKey;
  // Whether the alt key was pressed.
  boolean altKey;
  // Whether the shift key was pressed.
  boolean shiftKey;
  // Whether the ctrl key was pressed.
  boolean ctrlKey;
};

// The current braille display state.
dictionary DisplayState {
  // Whether a braille display is currently available.
  required boolean available;
  // Number of rows of braille cells on the currently connected display.
  long textRowCount;
  // Number of columns of braille cells on the currently connected display.
  long textColumnCount;
  // The number of dots in a braille cell on the currently connected display.
  long cellSize;
};

// Listener callback for the onDisplayStateChanged event.
callback OnDisplayStateChangedListener = undefined (DisplayState state);

interface OnDisplayStateChangedEvent : ExtensionEvent {
  static undefined addListener(OnDisplayStateChangedListener listener);
  static undefined removeListener(OnDisplayStateChangedListener listener);
  static boolean hasListener(OnDisplayStateChangedListener listener);
};

// Listener callback for the onKeyEvent event.
callback OnKeyEventListener = undefined (KeyEvent event);

interface OnKeyEventEvent : ExtensionEvent {
  static undefined addListener(OnKeyEventListener listener);
  static undefined removeListener(OnKeyEventListener listener);
  static boolean hasListener(OnKeyEventListener listener);
};

// Braille display access private API.
interface BrailleDisplayPrivate {
  // Gets the current display state.
  // |PromiseValue|: result
  static Promise<DisplayState> getDisplayState();

  // Write the given dot patterns to the display.  The buffer contains one
  // byte for each braille cell on the display, starting from the leftmost
  // cell. Each byte contains a bit pattern indicating which dots should be
  // raised in the corresponding cell with the low-order bit representing
  // dot 1 and so on until bit 7 which corresponds to dot 8.  If the number
  // of bytes in the buffer is not equal to the display size, the buffer
  // will either be clipped or padded with blank cells on the right. The
  // buffer is a 2D array compressed into 1D. The |columns| and |rows|
  // parameters give the original 2D dimensions of the buffer. To access
  // an element cells[r][c], simply access cells[r * columns + c].
  static undefined writeDots(ArrayBuffer cells, long columns, long rows);

  // Updates the single user-preferred braille device with the given bluetooth
  // device address and starts or restarts the Brltty daemon.
  static undefined updateBluetoothBrailleDisplayAddress(DOMString address);

  // Fired when a braille display is connected or disconnected.
  static attribute OnDisplayStateChangedEvent onDisplayStateChanged;

  // Fired when an input event is received from the display.
  static attribute OnKeyEventEvent onKeyEvent;
};

partial interface Browser {
  static attribute BrailleDisplayPrivate brailleDisplayPrivate;
};