@datasworn-community/build-tools 0.2.0

package/schema-source/schema/common/Inputs.ts

@@ -0,0 +1,374 @@
+/** Abstract inputs that are used by option and control fields.  */
+import {
+	type ObjectOptions,
+	type Static,
+	type TInteger,
+	type TLiteral,
+	type TObject,
+	type TRefUnsafe,
+	type TSchema,
+	type TString,
+	Type
+} from '@sinclair/typebox'
+import JtdType from '../../scripts/json-typedef/typedef.js'
+import * as Generic from '../Generic.js'
+import { JsonTypeDef } from '../Symbols.js'
+import * as Utils from '../Utils.js'
+import { Assign } from '../utils/FlatIntersect.js'
+import type { ObjectProperties } from '../utils/ObjectProperties.js'
+import {
+	LiteralZero,
+	setDescriptions,
+	type TFuzzySchemaOf
+} from '../utils/typebox.js'
+import * as Text from './Text.js'
+
+/**
+ * @abstract
+ */
+export function Input<Value extends TSchema>(
+	value: Value,
+	options: ObjectOptions = {}
+) {
+	return Type.Object(
+		{
+			label: Type.Ref(Text.Label),
+			value: {
+				description: 'The current value of this input.',
+				...value
+			} as Value
+		},
+		options
+	) satisfies TInput<Value>
+}
+export type TInput<Value extends TSchema> = TObject<{
+	label: TRefUnsafe<TString>
+	value: Value
+}>
+export interface Input<Value> {
+	label: string
+	value: Value
+}
+
+/**
+ * Represents a range of number values with a minimum and a maximum.
+ * @template Min The schema of the minimum value
+ * @template Max The schema of the maximum value
+ * @abstract
+ */
+export function Range<
+	Min extends TFuzzySchemaOf<number>,
+	Max extends TFuzzySchemaOf<number>
+>({ min, max }: { min: Min; max: Max }, options: ObjectOptions = {}) {
+	return setDescriptions(
+		Type.Object({ min, max }, options),
+		{
+			min: 'The (inclusive) minimum value.',
+			max: 'The (inclusive) maximum value.'
+		},
+		false
+	)
+}
+export type TRange<
+	Min extends TFuzzySchemaOf<number> = TFuzzySchemaOf<number>,
+	Max extends TFuzzySchemaOf<number> = TFuzzySchemaOf<number>
+> = TObject<{ min: Min; max: Max }>
+export interface Range<
+	Min extends number | null = number | null,
+	Max extends number | null = number | null
+> {
+	min: Min
+	max: Max
+}
+
+function IntegerInput<
+	Min extends TFuzzySchemaOf<number>,
+	Max extends TFuzzySchemaOf<number>,
+	Rollable extends TLiteral<boolean>
+>(
+	{ min, max, rollable }: { min: Min; max: Max; rollable: Rollable },
+	options: ObjectOptions = {}
+) {
+	const mixin = Assign(
+		Input(
+			Type.Integer({ default: 0, [JsonTypeDef]: { schema: JtdType.Int8() } })
+		),
+		Range({
+			min: { [JsonTypeDef]: { schema: JtdType.Int8() }, ...min },
+			max: { [JsonTypeDef]: { schema: JtdType.Int8() }, ...max }
+		})
+	)
+
+	return Assign(
+		mixin,
+		Type.Object({
+			rollable: {
+				[JsonTypeDef]: { schema: JtdType.Boolean() },
+				default: rollable.const,
+				...rollable
+			}
+		}),
+
+		options
+	) as unknown as TIntegerInput<Min, Max, Rollable>
+}
+export type TIntegerInput<
+	Min extends TFuzzySchemaOf<number> = TFuzzySchemaOf<number>,
+	Max extends TFuzzySchemaOf<number> = TFuzzySchemaOf<number>,
+	Rollable extends TLiteral<boolean> = TLiteral<boolean>
+> = TObject<{
+	label: TRefUnsafe<TString>
+	min: Min
+	max: Max
+	rollable: Rollable
+	value: TInteger
+}>
+
+// TInput<TInteger> &
+// 	TRange<Min, Max>
+
+export const Counter: TIntegerInput<
+	TInteger,
+	Utils.TNullable<TInteger>,
+	TLiteral<false>
+> = IntegerInput(
+	{
+		min: Type.Integer({ default: 0 }),
+		max: Utils.Nullable(Type.Integer(), {
+			default: null,
+			description:
+				"The (inclusive) maximum value, or `null` if there's no maximum."
+		}),
+		rollable: Type.Literal(false)
+	},
+	{
+		description:
+			'A basic counter representing a non-rollable integer value. They usually start at 0, and may or may not have a maximum.',
+		remarks: 'Semantics are similar to `<input type="number" step="1">`'
+	}
+) satisfies TInput<TInteger>
+
+export type TCounter = typeof Counter
+
+export type Counter = Static<TCounter>
+
+// value: 'The current number of filled clock segments.',
+export const Clock = IntegerInput(
+	{
+		min: {
+			...LiteralZero,
+			description:
+				'The minimum number of filled clock segments. This is always 0.'
+		} as TLiteral<0>,
+		max: Type.Integer({
+			title: 'ClockSize',
+			multipleOf: 2,
+			minimum: 2,
+			// examples: [4, 6, 8, 10],
+			description:
+				'The size of the clock -- in other words, the maximum number of filled clock segments. Standard clocks have 4, 6, 8, or 10 segments.'
+		}),
+		rollable: Type.Literal(false)
+	},
+	{
+		description: 'A clock with 4 or more segments.',
+		remarks:
+			'Semantics are similar to HTML `<input type="number">`, but rendered as a clock (a circle with equally sized wedges).'
+	}
+)
+export type TClock = typeof Clock
+export type Clock = Static<typeof Clock>
+
+/**
+ * A meter with an integer value, bounded by a minimum and maximum
+ * @abstract
+ */
+export function Meter<Rollable extends TLiteral<boolean>>(
+	rollable: Rollable,
+	options: ObjectOptions = {}
+) {
+	return setDescriptions(
+		IntegerInput(
+			{
+				min: Type.Integer({
+					default: 0,
+					description: 'The minimum value of this meter.'
+				}),
+				max: Type.Integer({ description: 'The maximum value of this meter.' }),
+				rollable: {
+					description:
+						"Is this meter's `value` usable as a stat in an action roll?",
+					...rollable
+				}
+			},
+			{
+				description:
+					'A meter with an integer value, bounded by a minimum and maximum.',
+				...options
+			}
+		),
+		{
+			value: 'The current value of this meter.'
+		}
+	)
+}
+
+export type TMeter<Rollable extends TLiteral<boolean> = TLiteral<boolean>> =
+	ReturnType<typeof Meter<Rollable>>
+export type Meter<Rollable extends boolean = boolean> = Static<
+	TMeter<TLiteral<Rollable>>
+>
+
+/**
+ * Represents a checkbox, similar to an HTML `<input type="checkbox">` element.
+ * @abstract
+ */
+export const Checkbox = Input(
+	Type.Boolean({ description: 'Is the box checked?', default: false }),
+	{
+		description: 'Represents a checkbox.',
+		remarks: 'Semantics are similar to the `<input type="checkbox">` element.'
+	}
+)
+export type Checkbox = Static<typeof Checkbox>
+export type TCheckbox = typeof Checkbox
+
+export const TextInput = Input(
+	Utils.Nullable(Type.String(), {
+		description: "The content of this text input, or `null` if it's empty",
+		default: null
+	}),
+	{
+		description: 'Represents an input that accepts plain text.',
+		remarks: 'Semantics are similar to the HTML `<input type="text">` element.'
+	}
+)
+export type TextInput = Static<typeof TextInput>
+export type TTextInput = typeof TextInput
+
+/**
+ * Represents an option in a list of choices.
+ * @abstract
+ */
+const SelectOptionBase = Type.Object({
+	label: Type.Ref(Text.Label),
+	choice_type: Type.Literal('choice')
+})
+
+export function SelectOption<T extends TObject>(
+	schema: T,
+	options: ObjectOptions = {}
+) {
+	return Assign(SelectOptionBase, schema, {
+		description: 'Represents an option in a list of choices.',
+		remarks: 'Semantics are similar to the HTML `<option>` element.',
+		...options
+	})
+}
+export type TSelectChoice<T extends TObject> = ReturnType<
+	typeof SelectOption<T>
+>
+export type SelectChoice<T extends object> = T & Static<typeof SelectOptionBase>
+
+function Choices<T extends TSchema>(
+	choiceSchema: T,
+	options: ObjectOptions = {}
+) {
+	return Type.Object(
+		{
+			choices: Generic.Dictionary(choiceSchema)
+		},
+		options
+	)
+}
+export type TChoices<T extends TSchema> = ReturnType<typeof Choices<T>>
+export interface Choices<T> {
+	choices: Record<string, T>
+}
+
+const SelectChoicesGroupBase = Type.Object({
+	name: Type.Ref(Text.Label, {
+		description: 'A label for this option group.'
+	}),
+	choice_type: Type.Literal('choice_group')
+})
+export function SelectChoicesGroup<
+	TOption extends TRefUnsafe<TSelectChoice<TObject>> | TSelectChoice<TObject>
+>(optionSchema: TOption, options: ObjectOptions = {}) {
+	const mixin = Choices(optionSchema)
+	return Assign(SelectChoicesGroupBase, mixin, {
+		description: 'Represents a grouping of options in a list of choices.',
+		remarks: 'Semantics are similar to the HTML `<optgroup>` element.',
+		title: optionSchema.title ? `${optionSchema.title}Group` : undefined,
+		...options
+	}) as TObject<
+		ObjectProperties<typeof SelectChoicesGroupBase> &
+			ObjectProperties<typeof mixin>
+	>
+}
+export type TSelectChoicesGroup<
+	TOption extends TRefUnsafe<TSelectChoice<TObject>> | TSelectChoice<TObject>
+> = ReturnType<typeof SelectChoicesGroup<TOption>>
+
+export type SelectChoicesGroup<Option extends SelectChoice<any>> = Static<
+	typeof SelectChoicesGroupBase
+> &
+	Choices<Option>
+
+const SelectBase = Input(
+	Utils.Nullable(Type.Ref('DictKey'), {
+		description:
+			'The key of the currently selected choice from the `choices` property, or `null` if none is selected.',
+		default: null
+	})
+)
+
+export function SelectWithGroups<Option extends TSelectChoice<TObject>>(
+	choiceSchema: Option,
+	choicesGroupSchema: TSelectChoicesGroup<TRefUnsafe<Option> | Option>,
+	options: ObjectOptions = {}
+) {
+	const mixin = Choices(
+		Utils.DiscriminatedUnion(
+			{
+				choice: choiceSchema,
+				choice_group: choicesGroupSchema
+			},
+			'choice_type'
+		)
+	)
+	return Assign(SelectBase, mixin, {
+		description: 'Represents a list of mutually exclusive choices.',
+		remarks: 'Semantics are similar to the HTML `<select>` element',
+		...options
+	}) as TObject<
+		ObjectProperties<typeof SelectBase> & ObjectProperties<typeof mixin>
+	>
+}
+
+/**
+ * Represents a list of mutually exclusive choices.
+ * @remarks Semantics are similar to the HTML `<select>` element.
+ */
+export function Select<
+	Option extends TRefUnsafe<
+		| TSelectChoice<TObject>
+		| Utils.TDiscriminatedUnion<TSelectChoice<TObject>, string>
+	>
+>(choiceSchema: Option, options: ObjectOptions = {}) {
+	const mixin = Choices(choiceSchema)
+
+	return Assign(SelectBase, mixin, {
+		description: 'Represents a list of mutually exclusive choices.',
+		remarks: 'Semantics are similar to the HTML `<select>` element',
+		...options
+	}) as TObject<
+		ObjectProperties<typeof SelectBase> & ObjectProperties<typeof mixin>
+	>
+}
+export type TSelect<Option extends TRefUnsafe<TSelectChoice<TObject>>> =
+	ReturnType<typeof Select<Option>>
+export type Select<Option extends SelectChoice<any>> = Static<
+	typeof SelectBase
+> &
+	Choices<Option>

package/schema-source/schema/common/Metadata.ts

@@ -0,0 +1,142 @@
+import { type Static, Type } from '@sinclair/typebox'
+import JtdType from '../../scripts/json-typedef/typedef.js'
+import { JsonTypeDef } from '../Symbols.js'
+import { Nullable } from '../utils/Nullable.js'
+import { Label } from './Text.js'
+
+export const WebUrl = Type.String({
+	format: 'uri',
+	description: 'An absolute URL pointing to a website.',
+	$id: 'WebUrl'
+})
+export type WebUrl = Static<typeof WebUrl>
+
+export const SvgImageUrl = Type.String({
+	pattern: /\.svg$/i.source,
+	$id: 'SvgImageUrl',
+	format: 'uri-reference',
+	description:
+		'A relative (local) URL pointing to a vector image in the SVG format.'
+})
+export type SvgImageUrl = Static<typeof SvgImageUrl>
+export const WebpImageUrl = Type.String({
+	pattern: /\.webp$/i.source,
+	$id: 'WebpImageUrl',
+	format: 'uri-reference',
+	description:
+		'A relative (local) URL pointing to a raster image in the WEBP format.'
+})
+export type WebpImageUrl = Static<typeof WebpImageUrl>
+export const CssColor = Type.String({
+	$id: 'CssColor',
+	remarks: 'See https://developer.mozilla.org/en-US/docs/Web/CSS/color_value',
+	description: 'A CSS color value.'
+})
+export type CssColor = Static<typeof CssColor>
+
+export const SemanticVersion = Type.String({
+	pattern:
+		/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$/
+			.source,
+	$id: 'SemanticVersion'
+})
+export type SemanticVersion = Static<typeof SemanticVersion>
+
+export const Email = Type.String({
+	format: 'email',
+	description: 'An email address.',
+	$id: 'Email'
+})
+export type Email = Static<typeof Email>
+
+export const AuthorInfo = Type.Object(
+	{
+		name: Type.Ref(Label, {
+			description: 'The name of the author.',
+			examples: ['Shawn Tomkin']
+		}),
+		email: Type.Optional(
+			Type.Ref(Email, {
+				description: 'An optional email contact for the author'
+			})
+		),
+		url: Type.Optional(
+			Type.Ref(WebUrl, {
+				description: "An optional URL for the author's website."
+			})
+		)
+	},
+	{
+		examples: [{ name: 'Shawn Tomkin', url: 'https://ironswornrpg.com' }],
+		$id: 'AuthorInfo',
+		description: 'Information on the original creator of this material.'
+	}
+)
+
+export const PageNumber = Type.Integer({
+	minimum: 1,
+	description: 'Represents a page number in a book.',
+	$id: 'PageNumber',
+	[JsonTypeDef]: {
+		schema: Type.Optional(JtdType.Uint16())
+	}
+})
+
+export const SourceInfo = Type.Object(
+	{
+		title: Type.Ref(Label, {
+			description: 'The title of the source document.',
+			examples: [
+				'Ironsworn Rulebook',
+				'Ironsworn Assets Master Set',
+				'Ironsworn: Delve',
+				'Ironsworn: Starforged Rulebook',
+				'Ironsworn: Starforged Assets',
+				'Sundered Isles'
+			]
+		}),
+		page: Type.Optional(
+			Type.Ref(PageNumber, {
+				description: 'The page number where this content is described in full.'
+			})
+		),
+		authors: Type.Array(Type.Ref(AuthorInfo), {
+			minItems: 1,
+			description: 'Lists authors credited by the source material.'
+		}),
+		date: Type.String({
+			pattern: /[0-9]{4}-((0[0-9])|(1[0-2]))-(([0-2][0-9])|(3[0-1]))/.source,
+			format: 'date',
+			remarks: 'You may prefer to deserialize this as a Date object.',
+			[JsonTypeDef]: { schema: JtdType.String() },
+			description:
+				"The date of the source documents's last update, formatted YYYY-MM-DD. Required because it's used to determine whether the data needs updating."
+		}),
+		url: Type.Ref(WebUrl, {
+			description: 'A URL where the source document is available.',
+			examples: ['https://ironswornrpg.com']
+		}),
+		license: Nullable(Type.Ref(WebUrl), {
+			description:
+				"An URL pointing to the location where this content's license can be found.\n\nA `null` here indicates that the content provides __no__ license, and is not intended for redistribution.",
+			examples: [
+				'https://creativecommons.org/licenses/by/4.0',
+				'https://creativecommons.org/licenses/by-nc-sa/4.0'
+			]
+		})
+	},
+	{
+		description: 'Metadata describing the original source of this node',
+		$id: 'SourceInfo',
+		additionalProperties: true
+	}
+)
+
+export type SourceInfo = Static<typeof SourceInfo>
+
+export const Suggestions = Type.Array(Type.Ref('AnyIdWildcard'), {
+	$id: 'Suggestions',
+	releaseStage: 'experimental'
+})
+
+export type Suggestions = Static<typeof Suggestions>

package/schema-source/schema/common/Player.ts

@@ -0,0 +1,17 @@
+import { type Static, Type } from '@sinclair/typebox'
+import { DictKey } from './Id.js'
+
+export const StatKey = Type.Ref(DictKey, {
+	examples: ['edge', 'heart', 'iron', 'shadow', 'wits'],
+	$id: 'StatKey',
+	description: 'A basic player character stat.'
+})
+export type StatKey = Static<typeof StatKey>
+
+export const ConditionMeterKey = Type.Ref(DictKey, {
+	$id: 'ConditionMeterKey',
+	examples: ['health', 'spirit', 'supply'],
+	description:
+		'A basic, rollable player character resource specified by the ruleset.'
+})
+export type ConditionMeterKey = Static<typeof ConditionMeterKey>

package/schema-source/schema/common/Progress.ts

@@ -0,0 +1,63 @@
+import { type Static, Type } from '@sinclair/typebox'
+import * as Generic from '../Generic.js'
+import { UnionEnumFromRecord } from '../utils/UnionEnumFromRecord.js'
+import Id from './Id.js'
+import * as Text from './Text.js'
+
+export const ChallengeRank = UnionEnumFromRecord(
+	{
+		1: 'Troublesome',
+		2: 'Dangerous',
+		3: 'Formidable',
+		4: 'Extreme',
+		5: 'Epic'
+	},
+	{
+		$id: 'ChallengeRank',
+		description:
+			'Challenge rank, represented as an integer from 1 (troublesome) to 5 (epic).'
+	}
+)
+export type ChallengeRank = Static<typeof ChallengeRank>
+
+export const SpecialTrackType = Type.Ref(Id.DictKey, {
+	$id: 'SpecialTrackType',
+	examples: [
+		'bonds_track',
+		'failure_track',
+		'quests_legacy',
+		'bonds_legacy',
+		'discoveries_legacy'
+	],
+	description: `Special, ruleset-specific progress tracks. Usually, one exists per player character, and they persist through the life of the player character.
+'Canonical' examples:
+  * \`bonds_track\`, described in the Ironsworn Rulebook. For the Starforged legacy track, use \`bonds_legacy\` instead.
+  * \`failure_track\`, described in Ironsworn: Delve
+  * \`quests_legacy\`, \`bonds_legacy\`, and \`discoveries_legacy\`, described Ironsworn: Starforged
+
+`
+})
+
+export type SpecialTrackType = Static<typeof SpecialTrackType>
+export const ProgressTrackTypeInfo = Type.Object(
+	{
+		category: Type.Ref(Text.Label, {
+			description: 'A category label for progress tracks of this type.',
+			examples: [
+				'Vow',
+				'Journey',
+				'Combat',
+				'Scene Challenge',
+				'Expedition',
+				'Connection',
+				'Delve'
+			]
+		}),
+		controls: Type.Optional(Generic.Dictionary(Type.Object({})))
+	},
+	{
+		$id: 'ProgressTrackTypeInfo',
+		description: 'Describes the features of a type of progress track.'
+	}
+)
+export type ProgressTrackTypeInfo = Static<typeof ProgressTrackTypeInfo>

package/schema-source/schema/common/Range.ts

@@ -0,0 +1,53 @@
+import { type Static, Type } from '@sinclair/typebox'
+import { omit } from 'lodash-es'
+import JtdType from '../../scripts/json-typedef/typedef.js'
+import { JsonTypeDef } from '../Symbols.js'
+
+// const IntegerRange = Type.Object({
+// 	min: Type.Integer(),
+// 	max: Type.Integer()
+// })
+// export type IntegerRange = Static<typeof IntegerRange>
+
+const minOptions = {
+	description: 'Low end of the dice range.',
+	[JsonTypeDef]: {
+		schema: JtdType.Int16()
+	}
+}
+const maxOptions = {
+	description: 'High end of the dice range.',
+	[JsonTypeDef]: {
+		schema: JtdType.Int16()
+	}
+}
+
+const diceRangeOptions = {
+	description:
+		'Represents a range of dice roll results, bounded by `min` and `max` (inclusive).'
+}
+
+export const DiceRange = Type.Object(
+	{
+		min: Type.Integer(minOptions),
+		max: Type.Integer(maxOptions)
+	},
+	{
+		$id: 'DiceRange',
+		...diceRangeOptions
+	}
+)
+export type DiceRange = Static<typeof DiceRange>
+
+export function StaticDiceRange(min: number, max: number) {
+	return Type.Object(
+		{
+			min: Type.Const(min, omit(minOptions, ['description'])),
+			max: Type.Const(max, omit(maxOptions, ['description']))
+		},
+		{
+			title: 'DiceRangeStatic',
+			...omit(diceRangeOptions, ['description'])
+		}
+	)
+}