x4js 2.3.21 → 2.3.23

package/aicontext.md

@@ -41,7 +41,7 @@ CoreElement<E>                 named timers + event surface (no DOM)
   │     ├── CSizer → HSizer / VSizer
   │     ├── FileDialog, ScrollView, Viewport, DockingView, Flex, Space
   │     ├── HBox-based: ColorInput, Rating, Switch, Tag, Keyboard, TextEdit → AutoComplete, Breadcrumbs
-  │     └── VBox-based: Calendar, ColorPicker, FileDrop, Panel, PropertyGrid, TextArea
+  │     └── VBox-based: Calendar, ColorPicker, FileDrop, Panel, PropertyGrid, TextArea, SettingsView, SettingItem
   └── Application<E>           singleton, no DOM of its own
 
 EventSource<E>                 standalone event registry
@@ -1030,6 +1030,8 @@ interface ButtonProps extends ComponentProps {
   tabindex?: number | boolean
   autorepeat?: number | boolean            // true=200ms; number=interval (first fire after 500ms)
   click?: EventCallback<EvClick>
+  menu?: MenuElement[] | (() => MenuElement[])   // a click opens this Menu under the button, in place of the click event;
+                                           // a function is called at each click; the button gets the class "with-menu"
 }
 class Button extends Component {
   click(): void                            // simulate a click
@@ -1153,6 +1155,78 @@ class Form extends Box {
 
 ---
 
+## `SettingsView` — a page of settings, as the settings of VS Code
+
+The summary of the sections on the left, the sections on the right, one after the other, each a panel with its title on a band; in a section, each `SettingItem` with its name, what it does, then its controls. A click in the summary brings its section to the top; the summary follows the scroll and marks the section at the top of the view.
+
+```ts
+interface SettingItemProps extends BoxProps {
+  title: string
+  description?: string                     // under the name
+  content: Component | Component[]         // its controls, on a line that wraps
+}
+class SettingItem extends VBox {
+  getSearchText(): string                  // the title and the description: what a search looks in
+}
+// A SettingItem has no value of its own: its controls keep theirs. To read and write them together,
+// put the items in a Form (a section can hold a Form of SettingItem), give the controls a name,
+// and use getValues / setValues. The item is marked on its left while one of its controls has the focus.
+
+interface SettingsSection {
+  id: string
+  title: string
+  description?: string                     // under the title
+  content: Component[]                     // SettingItem, Form of SettingItem, or any component
+}
+interface SettingsViewProps extends BoxProps {
+  sections?: SettingsSection[]
+  searchable?: boolean                     // a search field above the sections
+  searchPlaceholder?: string               // _tr.global.settings.search when missing
+  noMatch?: string                         // shown when the search finds nothing; _tr.global.settings.nomatch when missing
+  sectionChange?: EventCallback<EvSectionChange>
+}
+interface EvSectionChange extends ComponentEvent { readonly section: string }   // the id of the section at the top
+class SettingsView<P extends SettingsViewProps = SettingsViewProps> extends VBox<P, SettingsViewEvents> {
+  setSections(sections: SettingsSection[]): void   // replaces the sections
+  showSection(id: string, smooth = true): void     // brings a section to the top
+  getSection(): string                             // the id of the section at the top
+}
+// Search: the words typed are looked for without case nor accents; an item is shown when its title or
+//   its description holds all of them. A section whose title or description holds them is shown whole;
+//   otherwise only its items that hold them, and what holds those items (a Form, a box). What holds no
+//   item (a table, a text) is shown with its whole section only. Escape empties the field.
+// The section marked in the summary is the last one whose top is above the top of the view (40px of
+//   margin); the first one while the view is hidden (in a tab not shown). The last section shown is at
+//   least as high as the view (class "last"): a click in the summary can bring any section to the top.
+// Classes: .x4settingsview > .search > .x4input, > .body > .toc (a Listbox), > .body > .sections;
+//   .section(.last) > .title, .description; .sections > .nomatch; .x4settingitem > .name, .description, .controls
+// CSS variables: --settingsview-toc-width, --settingsview-section-background,
+//   --settingsview-section-title-background, --settingsview-hover-background, --settingsview-marker
+```
+
+A page that builds its sections with references to its own components (`this.refs.x = ...`) cannot give them to `super()`: `this` is not there yet. It calls `setSections` after `super()`. `SettingsView` keeps its own parts in private fields, not in `refs`: `refs` is left to the classes that derive from it.
+
+```ts
+class MySettings extends SettingsView {
+  declare protected refs: { size: Input }
+
+  constructor(props: BoxProps) {
+    super({ ...props, searchable: true })
+
+    this.setSections([
+      { id: "editor", title: "Editor", content: [
+        new Form({ content: [
+          new SettingItem({ title: "Font size", description: "The size of the text, in pixels.",
+            content: this.refs.size = new Input({ type: "number", name: "fontSize", value: 14 }) }),
+        ] }),
+      ] },
+    ])
+  }
+}
+```
+
+---
+
 ## Sizers / viewport / misc
 
 ```ts
@@ -1184,7 +1258,10 @@ class ColorPicker extends VBox {           // props: color, swatches?, nullable?
 }
 class Panel extends VBox { setTitle(title: string): void }   // the text of its title: its icon stays
 class Breadcrumbs extends HBox { setItems(elements): void }
-interface KeyboardProps extends BoxProps { locale?: string }   // "fr-FR" (default), "de-CH", "pl"...
+interface KeyboardProps extends BoxProps {
+  locale?: string      // "fr-FR" (default), "de-CH", "pl"...
+  numpadOnly?: boolean    // number or date field: the pad has no "abc" key back to the letters
+}
 class Keyboard extends HBox {               // virtual keyboard, shown while an <input> has the focus
   setLocale(locale: string): void
   setZoom(perc: number): void
@@ -1192,6 +1269,7 @@ class Keyboard extends HBox {               // virtual keyboard, shown while an
 }
 // languages: cs da de en es et fi fr ga hr hu it lt lv mt nl pl pt ro sk sl sv
 // bottom row: 123 (numeric pad), the letters of the language (éè, none in en), the signs (#+=); Abc comes back
+// a key acts on pointerdown; the keys that draw the keyboard again (shift, 123, abc, accents, signs) on the click
 class TickLine extends Component
 class Header extends HBox                  // resizable column header; updates target style "--{name}-width"
 ```
@@ -1409,7 +1487,7 @@ dragManager.registerDropTarget(column, (cmd, el, infos) => {
 
 ## i18n (`core_i18n`)
 
-Two built-in languages (`fr` default, and `en`).
+Four built-in languages: `fr` (default), `en` (based on `fr`), `es` and `de` (based on `en`). Dates: `D/M/Y` in fr and es, `M/D/Y` in en, `D.M.Y` in de.
 
 ```ts
 export let _tr                             // current translation object (proxy)
@@ -1426,7 +1504,8 @@ isLanguage(name: string): boolean
 //   search search_tip required_field invalid_format invalid_email invalid_number invalid_date
 //   empty_list err_403 property value copy cut paste filedrop
 //   diff_date_seconds/minutes/hours, date_input_formats, date_format, date_time_format,
-//   day_short[] day_long[] month_short[] month_long[], keyboard.{next,numeric,alpha}
+//   day_short[] day_long[] month_short[] month_long[], keyboard.{next,numeric,alpha},
+//   settings.{search,nomatch}
 ```
 
 ---
@@ -1454,8 +1533,15 @@ class Timer { setTimeout; clearTimeout; setInterval; clearInterval; clearAllTime
 
 class Color {
   // new Color(value) | new Color(r,g,b,a?)   a: 0..1, default 1
+  // value: "#rgb", "#rrggbb", "#rrggbbaa", "rgb()", "rgba()", a name ("cyan", "transparent"), "var(--name)",
+  //   and any other colour the browser knows (hsl(), oklch(), color-mix()), read from the pixel it paints
   setValue(value): this; setRgb(r,g,b,a?): this; setHsv(h,s,v,a?): this; setAlpha(a): this
-  getAlpha(): number; lighten(percent): this
+  getAlpha(): number
+  lighten(percent): this; darken(percent): this   // toward white / black, 0-100, each component rounded
+  mix(other: Color, amount): this                  // amount 0-1: 0 keeps this color, 1 gives the other one; alpha too
+  luminance(): number                              // WCAG relative luminance, 0 (black) to 1 (white); alpha not used
+  contrast(other: Color): number                   // WCAG ratio, 1 to 21
+  textColor(light?: Color, dark?: Color): Color    // a copy of the one of the two that contrasts most with this color; white and black by default
   isInvalid(): boolean                     // the last setValue could not be read (the color is red); setRgb/setHsv make it valid
   toHexString(): string; toNumber(): number
   toRgbString(withAlpha = false): string   // "rgb(r,g,b)"; true: "rgba(r,g,b,0.500)" when not opaque, "rgb(...)" when opaque

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "x4js",
-  "version": "2.3.21",
+  "version": "2.3.23",
   "type": "module",
   "main": "src/x4.ts",
   "module": "src/x4.ts",

package/src/components/btngroup/btngroup.module.scss

@@ -15,7 +15,7 @@
  **/
 
  :root {
-	--btngroup-background: white;
+	--btngroup-background: var( --background-primary );
  }
 
 .x4btngroup {

package/src/components/btngroup/btngroup.ts

@@ -56,7 +56,12 @@ interface BtnGroupProps extends Omit<ComponentProps,"content"> {
 }
 
 /**
- * 
+ *
+ * @cssvar
+ * ```
+ * --btngroup-background
+ * ```
+ * a packed group draws its buttons with the --ol-button-* variables of Button
  */
 
 @class_ns( "x4" )

package/src/components/button/button.module.scss

@@ -32,15 +32,15 @@
 	--button-background-disabled: var( --disabled-background );
 	--button-color-disabled: var( --disabled-color );
 
-	--button-icon-color: rgb(255 255 255 / 64%);
+	--button-icon-color: var( --icon-color-active );
 
 	// outline
 	--ol-button-background: var( --background-primary );
-	--ol-button-background-active: #ccc;
+	--ol-button-background-active: var( --background-active );
 	--ol-button-color-active: var( --text-primary );
-	--ol-button-background-hover: #eee;
+	--ol-button-background-hover: var( --background-hover );
 	--ol-button-color-hover: var( --text-primary );
-	--ol-button-color-disabled: #ccc;
+	--ol-button-color-disabled: var( --disabled-color-light );
 
 	--ol-button-color: var( --text-primary );
 	--ol-button-border: var( --border );

package/src/components/button/button.ts

@@ -71,6 +71,14 @@ export interface ButtonProps extends ComponentProps {
 	 */
 	click?: EventCallback<EvClick>;
 
+	/**
+	 * A menu that a click opens under the button, in place of the click event.
+	 * A function is called at each click: it gives the items of that time.
+	 * The button gets the class "with-menu".
+	 *
+	 * @example
+	 * new Button( { label: "File", menu: [ { text: "Open", click: open }, "-", { text: "Quit", click: quit } ] } );
+	 */
 	menu?: MenuElement[] | (( ) => MenuElement[]);
 }
 
@@ -90,7 +98,19 @@ export interface ButtonProps extends ComponentProps {
  * 	--button-background-disabled
  * 	--button-color-disabled
  * 	--button-icon-color
+ * 	--ol-button-background
+ * 	--ol-button-color
+ * 	--ol-button-border
+ * 	--ol-button-icon-color
+ * 	--ol-button-background-hover
+ * 	--ol-button-color-hover
+ * 	--ol-button-background-active
+ * 	--ol-button-color-active
+ * 	--ol-button-color-disabled
+ * 	--ol-button-border-focus
+ * 	--ol-button-color-focus
  * ```
+ * the --ol-button-* variables are the ones of the outline buttons
  */
 
 @class_ns( "x4" )

package/src/components/calendar/calendar.module.scss

@@ -36,6 +36,7 @@
 
 	--calendar-header-color: var( --text-primary );
 	--calendar-out-color: var( --disabled-color-dark );
+	--calendar-day-color: var( --text-primary );
 }
 
 .x4calendar {
@@ -93,7 +94,7 @@
 			min-width: 28px;
 			min-height: 28px;
 			
-			color: var( --gray-900 );
+			color: var( --calendar-day-color );
 			text-align: center;
 			
 			.text {

package/src/components/calendar/calendar.ts

@@ -54,7 +54,7 @@ interface CalendarProps extends ComponentProps {
  * ```
  * --calendar-btn-background
  * --calendar-btn-color
- * --calendar-btn-color
+ * --calendar-btn-color-hover
  * --calendar-week-color
  * --calendar-week-color-hover
  * --calendard-day-background-hover
@@ -66,6 +66,7 @@ interface CalendarProps extends ComponentProps {
  * --calendar-today-border
  * --calendar-header-color
  * --calendar-out-color
+ * --calendar-day-color
  * ```
  */
 

package/src/components/chart/chart.module.scss

@@ -15,10 +15,10 @@
  **/
 
 :root {
-	--chart-background: white;
-	--chart-text: #52514e;
-	--chart-grid: #e6e5e0;
-	--chart-axis: #b5b4ae;
+	--chart-background: var( --background-primary );
+	--chart-text: var( --text-ternary );
+	--chart-grid: var( --border );
+	--chart-axis: var( --border-hover );
 
 	// series colors, used in this order
 	--chart-color-1: #2a78d6;

package/src/components/checkbox/checkbox.module.scss

@@ -24,6 +24,7 @@
 	--checkbox-color-disabled: var( --disabled-background );
 	--checkbox-check-border: var( --border );
 	--checkbox-check-border-hover: var( --border-hover );
+	--checkbox-check-color: var( --accent-color );
 }
 
 .x4checkbox {
@@ -41,7 +42,7 @@
 	.inner {
 		height: 1rem;
 		width: 1rem;
-		color: white;
+		color: var( --checkbox-check-color );
 		position: relative;
 		order: 1;
 		

package/src/components/checkbox/checkbox.ts

@@ -41,6 +41,7 @@ interface CheckboxProps extends ComponentProps {
  * --checkbox-color-disabled
  * --checkbox-check-border
  * --checkbox-check-border-hover
+ * --checkbox-check-color
  * ```
  */
 

package/src/components/colorpicker/colorpicker.module.scss

@@ -74,7 +74,6 @@
 			overflow: hidden;
 			
 			background-image: linear-gradient(to right, rgb(255, 0, 0), rgb(255, 255, 0), rgb(0, 255, 0), rgb(0, 255, 212), rgb(0, 0, 255), rgb(255, 0, 255), rgb(255, 0, 0));
-			border: 1px solid var( --color-gray-3 );
 
 			.thumb {
 				@include overlay-shadow;

package/src/components/components.ts

@@ -35,6 +35,7 @@ export * from "./propgrid/propgrid"
 export * from "./radio/radio"
 export * from "./rating/rating"
 export * from "./select/select"
+export * from "./settingsview/settingsview"
 export * from "./sizers/sizer"
 export * from "./slider/slider"
 export * from "./spreadsheet/spreadsheet"

package/src/components/dialog/dialog.module.scss

@@ -19,6 +19,7 @@
 :root {
 	--color-dialog-caption: var( --color-primary-a80 );
 	--color-dialog-caption-text: var( --color-primary-a0 );
+	--color-dialog-background: var( --background-primary );
 }
 
 .x4dialog {
@@ -26,8 +27,7 @@
 	@extend %vbox;
 
 	position: absolute !important;
-	background-color: white;
-	border: 1px solid var( --border-dark );
+	background-color: var( --color-dialog-background );
 	max-width: 99vw;
 	outline: none;
 	

package/src/components/dialog/dialog.ts

@@ -54,6 +54,7 @@ interface DialogEvents extends PopupEvents {
  * ```
  * --color-dialog-caption
  * --color-dialog-caption-text
+ * --color-dialog-background
  * ```
  */
 

package/src/components/dockingview/dockingview.module.scss

@@ -15,13 +15,14 @@
  **/
 
 .x4dockingview {
-	--dock-line: var( --border, #cfdae0 );						// between two panels, under a title
-	--dock-title-background: var( --background-secondary, #f3f7f9 );
-	--dock-title-background-hover: color-mix( in srgb, var( --dock-accent ) 25%, transparent );
-	--dock-title-color: var( --text-ternary, #607784 );
-	--dock-title-color-active: var( --text-primary, #002a40 );
-	--dock-accent: var( --accent-background, #126e9e );			// the tab in front, the sizer under the pointer, the preview
-	--dock-float-background: var( --background-primary, white );
+	--dock-line: var( --border );						// between two panels, under a title
+	--dock-title-background: var( --background-secondary );
+	--dock-title-background-hover: var( --accent-background-light );
+	--dock-title-color: var( --text-ternary );
+	--dock-title-color-active: var( --text-primary );
+	--dock-accent: var( --accent-background );			// the tab in front, the sizer under the pointer, the border of the preview
+	--dock-preview-background: var( --accent-background-light );	// where the panel that is dragged will go
+	--dock-float-background: var( --background-primary );
 	--dock-float-shadow: 0 6px 24px rgba( 0, 0, 0, 0.35 );
 
 	position: relative;
@@ -279,7 +280,7 @@
 		box-sizing: border-box;
 		pointer-events: none;
 
-		background: color-mix( in srgb, var( --dock-accent ) 30%, transparent );
+		background: var( --dock-preview-background );
 		border: 1px solid var( --dock-accent );
 		border-radius: 3px;
 	}

package/src/components/dockingview/dockingview.ts

@@ -179,6 +179,7 @@ interface Drag {
  * --dock-title-background-hover
  * --dock-title-color
  * --dock-title-color-active
+ * --dock-preview-background
  * --dock-float-background
  * --dock-float-shadow
  * ```

package/src/components/form/form.module.scss

@@ -17,7 +17,7 @@
  @use "../shared.scss";
 
 :root {
-	--form--background: var( --background-primary );
+	--form-background: transparent;
 }
 
 .x4form {
@@ -25,7 +25,7 @@
 	@extend %flex;
     
     padding: 16px;
-	background-color: var( --color-form );
+	background-color: var( --form-background );
 	
     &.horizontal {
         flex-direction: row;

package/src/components/form/form.ts

@@ -31,7 +31,7 @@ type ValidationFn = ( values: FormValues, is_valid: boolean ) => boolean;
 /**
  * @cssvar
  * ```
- * --form--background
+ * --form-background
  * ```
  */
 

package/src/components/gauge/gauge.module.scss

@@ -16,8 +16,8 @@
 
 :root {
 	--gauge-base-color: var( --color-primary-a70 );
-	--gauge-needle-back: black;
-	--gauge-needle-dot: rgb(58, 58, 58);
+	--gauge-needle-back: var( --text-primary );
+	--gauge-needle-dot: var( --text-ternary );
 }
 
 .x4gauge {

package/src/components/gridview/gridview.module.scss

@@ -346,7 +346,6 @@
 
 		.cell-out {
 			position: absolute;
-			background-color: var( --color-gray-0 );
 			width: 100%;
 			height: var( --row-height );
 		}

package/src/components/input/input.module.scss

@@ -15,8 +15,8 @@
  **/
 
 :root {
-    --input-background: rgba(255, 255, 255, 0.6);
-    --input-color: black;
+    --input-background: var( --background-input );
+    --input-color: var( --text-primary );
 
 	--input-sel-background: var( --accent-background );
 	--input-sel-color: var( --accent-color );

package/src/components/input/input.ts

@@ -203,6 +203,9 @@ interface InputEvents extends ComponentEvent {
  * 
  * @cssvar
  * ```
+ * --input-background
+ * --input-color
+ * --input-color-disabled
  * --input-sel-background
  * --input-sel-color
  * --input-placeholder

package/src/components/keyboard/keyboard.ts

@@ -239,6 +239,14 @@ function accentLabel( layout: KbLayout, upper: boolean ): string {
 	return ( upper ? upperKeys( label ) : label ).replace( " ", "" );
 }
 
+/**
+ * the keys that draw the keyboard again: shift, 123, abc, accents, signs
+ */
+
+function redrawKey( key: number ) {
+	return key==4 || key==5 || key==8 || key==10 || key==11;
+}
+
 
 const RE_sel = /text|password|search|tel|url/i;
 
@@ -248,6 +256,12 @@ interface KeyboardProps extends BoxProps {
 	 * "de-CH", "pl"... "fr-FR" when it is not given
 	 */
 	locale?: string;
+
+	/**
+	 * on a number or date field, the keyboard stays on the pad: no "abc" key
+	 * back to the letters. The other fields keep all the keys.
+	 */
+	numpadOnly?: boolean;
 }
 
 /**
@@ -284,7 +298,8 @@ export class Keyboard extends HBox<KeyboardProps>
 
 		this.hide( );
 
-		// a key: each contact, a finger or the mouse, the second tap of a quick double tap too
+		// a key: each contact, a finger or the mouse, the second tap of a quick double tap too.
+		// not the keys that draw the keyboard again, they act on the click
 		this.addDOMEvent( "pointerdown", (e) => {
 			this.handleKeyEvent( e );
 		});
@@ -352,7 +367,7 @@ export class Keyboard extends HBox<KeyboardProps>
             target = target.parentNode as HTMLElement;
         }
 
-		if( !key ) {
+		if( !key || redrawKey( key ) ) {
 			return;
 		}
 
@@ -631,6 +646,11 @@ export class Keyboard extends HBox<KeyboardProps>
 
 		if( this.mode=="number" || this.mode=="date" ) {
 			lines = kb_pads[this.mode];
+
+			// no key back to the letters: its place stays empty
+			if( this.props.numpadOnly ) {
+				lines = lines.map( line => line.replace( "{8}", "{9}" ) );
+			}
 		}
 		else if( this.mode=="accents" ) {
 			lines = accentLines( layout, this.upper );
@@ -765,7 +785,9 @@ export class Keyboard extends HBox<KeyboardProps>
 					icon, 
 					autorepeat: repeat, 
 					click: ( e ) => {
-						if( e.repeat ) {
+						// the keys that draw the keyboard again act on the click: the mousedown
+						// that follows a pointerdown would go to a key no longer in the page
+						if( e.repeat || redrawKey( key ) ) {
 							this._handleKey( key )
 						}
 					}

package/src/components/label/label.module.scss

@@ -19,7 +19,7 @@
 :root {
 	--label-background: transparent;
 	--label-color: var( --text-ternary );
-	--label-icon-color: rgb(0 0 0 / 44%);
+	--label-icon-color: var( --icon-color );
 	--label-color-disa: var( --disabled-color-dark );
 }
 

package/src/components/listbox/listbox.module.scss

@@ -28,9 +28,12 @@
 	--listbox-item-color-hover: var( --text-primary );;
 	--listbox-item-background-hover: var( --background-secondary );
 
-	--listbox-background: white;
+	--listbox-background: var( --background-primary );
 	--listbox-border: var( --border );
 	--listbox-border-focus: var( --accent-background-focus );
+
+	--listbox-title-background: var( --background-primary );
+	--listbox-title-color: var( --text-primary );
 }
 
 .x4listbox {
@@ -48,10 +51,10 @@
 	}
 
 	&>.title {
-	    background: white;
+	    background: var( --listbox-title-background );
 		padding: 4px;
 		font-weight: bold;
-		color: black;
+		color: var( --listbox-title-color );
 		border-bottom: 1px solid var(--border);
 	}
 

package/src/components/listbox/listbox.ts

@@ -88,6 +88,8 @@ export interface ListboxProps extends Omit<ComponentProps,'content'> {
  * --listbox-background
  * --listbox-border
  * --listbox-border-focus
+ * --listbox-title-background
+ * --listbox-title-color
  * ```
  */
 

package/src/components/menu/menu.module.scss

@@ -17,7 +17,7 @@
 @use "../shared.scss";
 
 :root {
-	--menu-background: white;
+	--menu-background: var( --background-primary );
 	--menu-border: var( --border-hover );
 
 	--menuitem-color: var( --text-ternary );;
@@ -33,7 +33,6 @@
 	position: absolute;
 	overflow-y: auto;
 
-	border-radius: var(--bradius);
 	padding: 8px 0;
 	min-width: 150px;