fansunited-widget-sports-data 0.0.1

package/README.md

@@ -0,0 +1 @@
+# Documentation about the widget

package/components/Main.d.ts

@@ -0,0 +1,14 @@
+import { default as React } from 'react';
+import { default as LabelsModel } from '../models/Labels/LabelsModel';
+type MainProps = {
+    fansUnitedApiKey: string;
+    fansUnitedClientId: string;
+    /** Display name for the client. Falls back to the client id when omitted. */
+    fansUnitedClientName?: string;
+    fansUnitedLanguage?: string;
+    fansUnitedEnvironment?: string;
+    labels?: LabelsModel;
+    hideSignOutButton?: boolean;
+};
+declare const Main: React.FC<MainProps>;
+export default Main;

package/components/MainLayout.d.ts

@@ -0,0 +1,9 @@
+import { default as React } from 'react';
+type MainLayoutProps = {
+    hideSignOutButton: boolean;
+    fansUnitedEnvironment: string;
+    fansUnitedClientId: string;
+    fansUnitedClientName?: string;
+};
+declare const MainLayout: React.FC<MainLayoutProps>;
+export default MainLayout;

package/components/SportData/AssetsSection.d.ts

@@ -0,0 +1,41 @@
+import { default as React } from 'react';
+import { AssetRow, AssetSlot } from '../../helpers/assets';
+export type AssetLabels = {
+    uploadedChip: string;
+    externalChip: string;
+    replace: string;
+    remove: string;
+    chooseFile: string;
+    dropHere: string;
+    useExternalUrl: string;
+    externalUrlPlaceholder: string;
+    saveUrl: string;
+    cancel: string;
+    storedPathNote: string;
+    externalUrlNote: string;
+    uploading: string;
+};
+type AssetsSectionProps = {
+    assets: AssetRow[];
+    slots: AssetSlot[];
+    readOnly: boolean;
+    labels: AssetLabels;
+    summary: string;
+    onUpload: (file: File, assetKey: string) => Promise<{
+        path: string;
+        url: string;
+    }>;
+    onChange: (assets: AssetRow[]) => void;
+    onError: (message: string) => void;
+};
+/**
+ * Images for an entity, one card per slot the type offers.
+ *
+ * Two ways in, and they store different things. An uploaded file goes through
+ * the proxy into Cloud Storage and is stored as a CDN-relative path; an external
+ * URL is stored verbatim and stays hosted wherever it already lives. The chip on
+ * each card says which of the two it is, because that is the difference between
+ * an image we control and one that can disappear without warning.
+ */
+declare const AssetsSection: React.FC<AssetsSectionProps>;
+export default AssetsSection;

package/components/SportData/BrandingSection.d.ts

@@ -0,0 +1,31 @@
+import { default as React } from 'react';
+import { BrandColorSlot, ShirtColors } from '../../helpers/branding';
+export type BrandingLabels = {
+    notSet: string;
+    clear: string;
+    shirtColorsHeading: string;
+    addShirt: string;
+    removeShirt: string;
+    shirtPrimary: string;
+    shirtSecondary: string;
+    summary: string;
+};
+type BrandingSectionProps = {
+    branding: Record<string, unknown>;
+    colorSlots: BrandColorSlot[];
+    shirts: ShirtColors[];
+    showShirts: boolean;
+    readOnly: boolean;
+    labels: BrandingLabels;
+    onColorChange: (key: string, value: string | null) => void;
+    onShirtsChange: (shirts: ShirtColors[]) => void;
+};
+/**
+ * Brand colours for an entity, and a team's kit colours.
+ *
+ * The colours are not decoration inside this widget either - `avatarColorOf`
+ * renders every row's avatar on the primary colour, so what is set here is
+ * visible in the list the moment it is saved.
+ */
+declare const BrandingSection: React.FC<BrandingSectionProps>;
+export default BrandingSection;

package/components/SportData/CatalogueScopeTabs.d.ts

@@ -0,0 +1,17 @@
+import { default as React } from 'react';
+/** Which index the list is reading: the shared catalogue, or one client's overlay. */
+export type CatalogueScope = 'global' | 'overrides';
+type CatalogueScopeTabsProps = {
+    value: CatalogueScope;
+    globalLabel: string;
+    overridesLabel: string;
+    onChange: (scope: CatalogueScope) => void;
+};
+/**
+ * Global catalogue / overrides switch.
+ *
+ * This is the control that decides whether reads and writes carry a `clientId`,
+ * so it is the visible form of the rule that `null` means the global catalogue.
+ */
+declare const CatalogueScopeTabs: React.FC<CatalogueScopeTabsProps>;
+export default CatalogueScopeTabs;

package/components/SportData/CopyableId.d.ts

@@ -0,0 +1,9 @@
+import { default as React } from 'react';
+type CopyableIdProps = {
+    id: string;
+    copyLabel: string;
+    copiedLabel: string;
+};
+/** An entity id that copies itself, used wherever an id is shown. */
+declare const CopyableId: React.FC<CopyableIdProps>;
+export default CopyableId;

package/components/SportData/EntitiesTable.d.ts

@@ -0,0 +1,40 @@
+import { default as React } from 'react';
+import { IkebanaEntity } from 'fansunited-management-components';
+import { CountryRef } from '../../services/SportEntitiesService';
+export type RowAction = {
+    key: string;
+    label: string;
+    variant: 'solid' | 'outlined' | 'plain';
+    color: 'primary' | 'neutral' | 'warning' | 'danger';
+    onClick: (entity: IkebanaEntity) => void;
+};
+type EntitiesTableProps = {
+    entities: IkebanaEntity[];
+    countries: Map<string, CountryRef>;
+    actionsFor: (entity: IkebanaEntity) => RowAction[];
+    onOpen: (entity: IkebanaEntity) => void;
+    /** Bulk-override selection. Hidden outside the global catalogue, which is the
+        only scope where creating an override makes sense. */
+    showSelect: boolean;
+    selectedIds: Record<string, boolean>;
+    /**
+     * Entities this client already overrides. Badged, and not selectable - creating
+     * a second override for the same id would just overwrite the first.
+     */
+    overriddenIds: Set<string>;
+    /** Badge copy, and its tooltip. Only shown while browsing the global catalogue. */
+    overriddenLabel: string;
+    overriddenTitle: string;
+    showOverriddenBadge: boolean;
+    onToggleSelect: (id: string) => void;
+    onToggleSelectAll: () => void;
+    nameColumn: string;
+    countryColumn: string;
+    actionsColumn: string;
+    notAvailableLabel: string;
+    copyIdLabel: string;
+    copiedIdLabel: string;
+    emptyMessage: string;
+};
+declare const EntitiesTable: React.FC<EntitiesTableProps>;
+export default EntitiesTable;

package/components/SportData/EntityBanner.d.ts

@@ -0,0 +1,19 @@
+import { default as React } from 'react';
+import { ColorPaletteProp } from '@mui/joy/styles';
+export type BannerIcon = 'global' | 'overrides' | 'readOnly' | 'new';
+type EntityBannerProps = {
+    title: string;
+    text: string;
+    color: ColorPaletteProp;
+    icon: BannerIcon;
+};
+/**
+ * States, in the editor, what saving will do and who it reaches.
+ *
+ * Separate from the list's ScopeNote despite looking similar: this one leads with
+ * a bold claim ("Editing the GLOBAL entity") because the consequence differs per
+ * state and is the thing a reader must not skim past. Publishing to every client
+ * and editing one client's private copy look identical in the form below it.
+ */
+declare const EntityBanner: React.FC<EntityBannerProps>;
+export default EntityBanner;

package/components/SportData/EntityEditor.d.ts

@@ -0,0 +1,27 @@
+import { default as React } from 'react';
+import { CatalogueScope } from './CatalogueScopeTabs';
+import { IkebanaEntityType } from 'fansunited-management-components';
+type EntityEditorProps = {
+    /** Empty while creating - there is no document to load yet. */
+    entityId: string;
+    /** Name from the row that was opened, shown until the document arrives. */
+    knownName?: string;
+    /** Creating rather than editing: nothing is fetched, and the id is unlocked. */
+    isNew?: boolean;
+    /** Sport code to seed a new entity's id and sport with, e.g. 'fb'. */
+    newSportCode?: string | null;
+    /** Called with the new id once a create succeeds, so the parent can switch to editing it. */
+    onCreated?: (id: string) => void;
+    entityType: IkebanaEntityType;
+    scope: CatalogueScope;
+    /** Display name for the client. */
+    clientName: string;
+    /** The client whose overlay is read when the scope is `overrides`. */
+    clientId: string;
+    canEdit: boolean;
+    /** Switches this editor onto the client's copy once one exists. */
+    onOverrideCreated?: () => void;
+    onBack: () => void;
+};
+declare const EntityEditor: React.FC<EntityEditorProps>;
+export default EntityEditor;

package/components/SportData/EntityTypeTabs.d.ts

@@ -0,0 +1,9 @@
+import { default as React } from 'react';
+import { IkebanaEntityType } from 'fansunited-management-components';
+type EntityTypeTabsProps = {
+    value: IkebanaEntityType;
+    onChange: (entityType: IkebanaEntityType) => void;
+};
+/** The seven entity type tabs across the top of the catalogue. */
+declare const EntityTypeTabs: React.FC<EntityTypeTabsProps>;
+export default EntityTypeTabs;

package/components/SportData/GeneralSection.d.ts

@@ -0,0 +1,13 @@
+import { default as React } from 'react';
+import { FieldDef } from '../../helpers/entityFields';
+type GeneralSectionProps = {
+    fields: FieldDef[];
+    values: Record<string, string>;
+    errors: Record<string, string>;
+    readOnly: boolean;
+    /** Locked fields become editable while creating, and never afterwards. */
+    isNew: boolean;
+    onChange: (field: FieldDef, value: string) => void;
+};
+declare const GeneralSection: React.FC<GeneralSectionProps>;
+export default GeneralSection;

package/components/SportData/JsonDrawer.d.ts

@@ -0,0 +1,27 @@
+import { default as React } from 'react';
+export type JsonDrawerLabels = {
+    globalSubtitle: string;
+    overrideSubtitle: string;
+    copy: string;
+    copied: string;
+    close: string;
+    footerNote: string;
+};
+type JsonDrawerProps = {
+    open: boolean;
+    title: string;
+    entityId: string;
+    isOverride: boolean;
+    /** The entity data a save would send, already normalised. */
+    json: string;
+    labels: JsonDrawerLabels;
+    onClose: () => void;
+};
+/**
+ * The entity data this editor would save, as JSON.
+ *
+ * Read-only on purpose: editing it would be a second way to write the same
+ * entity, with none of the validation.
+ */
+declare const JsonDrawer: React.FC<JsonDrawerProps>;
+export default JsonDrawer;

package/components/SportData/ListPagination.d.ts

@@ -0,0 +1,20 @@
+import { default as React } from 'react';
+export declare const PAGE_SIZE_OPTIONS: number[];
+type ListPaginationProps = {
+    summary: string;
+    page: number;
+    pageCount: number;
+    pageSize: number;
+    rowsPerPageLabel: string;
+    onPageChange: (page: number) => void;
+    onPageSizeChange: (pageSize: number) => void;
+};
+/**
+ * Summary on the left, page size and numbered page controls on the right.
+ *
+ * Hand-rolled because Joy ships no Pagination component and pulling in the
+ * Material one would put a second design system in the table footer. The page
+ * numbers are windowed (see pageSlots) so a catalogue of thousands still fits.
+ */
+declare const ListPagination: React.FC<ListPaginationProps>;
+export default ListPagination;

package/components/SportData/ListToolbar.d.ts

@@ -0,0 +1,19 @@
+import { default as React } from 'react';
+import { ALL_SPORTS, SportCode } from '../../constants/constants';
+type ListToolbarProps = {
+    query: string;
+    onQueryChange: (query: string) => void;
+    sport: SportCode | typeof ALL_SPORTS;
+    onSportChange: (sport: SportCode | typeof ALL_SPORTS) => void;
+    /** Hidden for countries, which carry no sport and would filter to nothing. */
+    showSportFilter: boolean;
+    canCreate: boolean;
+    createLabel: string;
+    createHint: string;
+    searchPlaceholder: string;
+    allSportsLabel: string;
+    onCreate: () => void;
+};
+/** Search, sport filter and create, on the right of the scope tabs. */
+declare const ListToolbar: React.FC<ListToolbarProps>;
+export default ListToolbar;

package/components/SportData/OverrideConfirmModal.d.ts

@@ -0,0 +1,27 @@
+import { default as React } from 'react';
+import { IkebanaEntity } from 'fansunited-management-components';
+type OverrideConfirmModalProps = {
+    open: boolean;
+    entities: IkebanaEntity[];
+    title: string;
+    subtitle: string;
+    bodyText: string;
+    startsFromNote: string;
+    reversibleNote: string;
+    moreLabel: string;
+    fewerLabel: string;
+    cancelLabel: string;
+    confirmLabel: string;
+    busy: boolean;
+    onCancel: () => void;
+    onConfirm: () => void;
+};
+/**
+ * Confirms creating client overrides, for one entity or many.
+ *
+ * Worth confirming rather than acting immediately: an override permanently
+ * detaches that entity from the global catalogue for this client - later global
+ * edits stop reaching it - and that consequence is invisible from the list.
+ */
+declare const OverrideConfirmModal: React.FC<OverrideConfirmModalProps>;
+export default OverrideConfirmModal;

package/components/SportData/RelatedSection.d.ts

@@ -0,0 +1,36 @@
+import { default as React } from 'react';
+import { IkebanaEntity, IkebanaEntityType } from 'fansunited-management-components';
+import { RelatedLink, RelationshipDef } from '../../helpers/related';
+export type RelatedLabels = {
+    addHeading: string;
+    searchPlaceholder: string;
+    noResults: string;
+    searching: string;
+    removeTitle: string;
+    unknownEntity: string;
+    unknownRelationship: string;
+    showMore: string;
+    showLess: string;
+    copyId: string;
+    copiedId: string;
+    empty: string;
+    summary: string;
+};
+type RelatedSectionProps = {
+    related: RelatedLink[];
+    relationships: RelationshipDef[];
+    /** Names for ids already linked, keyed by id. */
+    resolved: Map<string, IkebanaEntity>;
+    readOnly: boolean;
+    labels: RelatedLabels;
+    onSearch: (query: string, entityType: IkebanaEntityType) => Promise<IkebanaEntity[]>;
+    onChange: (related: RelatedLink[]) => void;
+};
+/**
+ * The entities this one is linked to.
+ *
+ * These are what the Search API filters on, so a link added here is what makes
+ * the entity answer a query like "every team in this competition".
+ */
+declare const RelatedSection: React.FC<RelatedSectionProps>;
+export default RelatedSection;

package/components/SportData/RemoveButton.d.ts

@@ -0,0 +1,20 @@
+import { default as React } from 'react';
+type RemoveButtonProps = {
+    title: string;
+    onClick: () => void;
+    /** `md` for headers, where the button stands alone rather than ending a row. */
+    size?: 'sm' | 'md';
+};
+/**
+ * The one way a row is removed, anywhere in the editor.
+ *
+ * Shared rather than repeated so the icon, size and hover cannot drift apart
+ * between sections - translations, attributes and provider references are the
+ * same gesture and should not look like three different ones.
+ *
+ * Only the glyph changes colour on hover. A tinted background reads as a
+ * destructive button being armed, which is the wrong weight for removing an
+ * unsaved row from a list.
+ */
+declare const RemoveButton: React.FC<RemoveButtonProps>;
+export default RemoveButton;

package/components/SportData/RemoveOverrideModal.d.ts

@@ -0,0 +1,23 @@
+import { default as React } from 'react';
+type RemoveOverrideModalProps = {
+    open: boolean;
+    title: string;
+    /** The entity being reset, named rather than identified by id. */
+    subtitle: string;
+    bodyText: string;
+    fallsBackNote: string;
+    permanentNote: string;
+    cancelLabel: string;
+    confirmLabel: string;
+    busy: boolean;
+    onCancel: () => void;
+    onConfirm: () => void;
+};
+/**
+ * Confirms deleting a client's override.
+ *
+ * Laid out like the create-override dialog on purpose: the two are opposite ends
+ * of the same action, and a reader who has seen one should recognise the other.
+ */
+declare const RemoveOverrideModal: React.FC<RemoveOverrideModalProps>;
+export default RemoveOverrideModal;

package/components/SportData/RowListSection.d.ts

@@ -0,0 +1,38 @@
+import { default as React } from 'react';
+export interface RowListRow {
+    /** Chosen from a fixed list - an attribute name, or a provider. */
+    key: string;
+    value: string;
+}
+type RowListSectionProps = {
+    rows: RowListRow[];
+    options: {
+        value: string;
+        label: string;
+    }[];
+    keyHeading: string;
+    valueHeading: string;
+    valuePlaceholder: string;
+    addLabel: string;
+    emptyMessage: string;
+    /** Tooltip on the remove button, e.g. "Remove provider reference". */
+    removeTitle: string;
+    readOnly: boolean;
+    /** Renders the value in monospace, for ids. */
+    monoValue?: boolean;
+    /** Shown above the empty-state message. */
+    emptyIcon: React.ReactNode;
+    /** Closing note, e.g. "2 provider references. Each provider should appear once." */
+    summary: string;
+    onChange: (rows: RowListRow[]) => void;
+};
+/**
+ * A list of key/value rows, backing both Additional Information and Provider
+ * References.
+ *
+ * One component for both because they are the same shape - a key from a fixed
+ * list, a free-text value, add and remove - and the only differences are the copy
+ * and whether the value reads as an id.
+ */
+declare const RowListSection: React.FC<RowListSectionProps>;
+export default RowListSection;

package/components/SportData/SaveStatus.d.ts

@@ -0,0 +1,16 @@
+import { default as React } from 'react';
+export type SaveState = 'clean' | 'dirty' | 'errors' | 'readOnly';
+type SaveStatusProps = {
+    state: SaveState;
+    text: string;
+};
+/**
+ * The save bar's state, as a chip rather than a line of grey text.
+ *
+ * The four states carry very different consequences - publishing to every client
+ * is not the same as having nothing to save - and flat text of one colour made
+ * them all look alike. The design marks this with a small coloured dot; this
+ * keeps that idea and lets the tint carry the severity.
+ */
+declare const SaveStatus: React.FC<SaveStatusProps>;
+export default SaveStatus;

package/components/SportData/ScopeNote.d.ts

@@ -0,0 +1,17 @@
+import { default as React } from 'react';
+import { ColorPaletteProp } from '@mui/joy/styles';
+type ScopeNoteProps = {
+    text: string;
+    color: ColorPaletteProp;
+    icon: 'global' | 'overrides' | 'readOnly';
+};
+/**
+ * The tinted band under the toolbar spelling out what editing in this scope does.
+ *
+ * Deliberately always present rather than dismissible: the difference between
+ * changing one client's data and changing every client's is the single most
+ * consequential thing on this screen, and it is not otherwise visible from the
+ * table.
+ */
+declare const ScopeNote: React.FC<ScopeNoteProps>;
+export default ScopeNote;

package/components/SportData/SearchIndexPanel.d.ts

@@ -0,0 +1,63 @@
+import { default as React } from 'react';
+import { IkebanaEntity } from 'fansunited-management-components';
+export type SearchPanelLabels = {
+    title: string;
+    hint: string;
+    nameStep: string;
+    nameStepHint: string;
+    variationsStep: string;
+    variationsStepHint: string;
+    noVariations: string;
+    filtersStep: string;
+    filtersStepHint: string;
+    noFilters: string;
+    moreFilters: string;
+    fewerFilters: string;
+    copyFilter: string;
+    copiedFilter: string;
+    showParams: string;
+    hideParams: string;
+    paramsHint: string;
+    paramsMore: string;
+    rankingStep: string;
+    rankingStepHint: string;
+    unfilterableWarning: string;
+};
+type SearchIndexPanelProps = {
+    labels: SearchPanelLabels;
+    /** The value of `search_title` this entity will be saved with. */
+    searchTitle: string;
+    /** The `search_variations` derived from the form. */
+    variations: string[];
+    /** `search_filters` - the only link field the Search API filters on. */
+    filters: {
+        relationship: string;
+        value: string;
+    }[];
+    /**
+     * Links stored under `relationships` instead of `search_filters`.
+     *
+     * Counted rather than listed because the point is only that they exist: the
+     * Search API never reads them, so they are invisible to filtering.
+     */
+    strandedLinkCount: number;
+    popularity: number;
+    /** Linked entities already loaded for Related, so nothing is fetched twice. */
+    resolved: Map<string, IkebanaEntity>;
+};
+/**
+ * What searching for this entity will actually do, in plain language.
+ *
+ * Written for whoever is editing the entity rather than for whoever built the
+ * index: the four steps are the four things that decide whether an app finds
+ * this entity and how high it appears, in the order a search applies them.
+ *
+ * Everything shown is derived from the form, not from the stored document - it
+ * is a preview of what saving would produce, which is the only version anyone
+ * can still change.
+ *
+ * Collapsed by default: General is where the editing happens, and this explains
+ * a consequence of it rather than asking for input.
+ */
+declare const SearchIndexPanel: React.FC<SearchIndexPanelProps>;
+export default SearchIndexPanel;

package/components/SportData/SeasonHistorySection.d.ts

@@ -0,0 +1,49 @@
+import { default as React } from 'react';
+import { SeasonEntry } from '../../helpers/seasonHistory';
+import { RelationshipDef } from '../../helpers/related';
+import { AssetLabels } from './AssetsSection';
+import { AssetSlot } from '../../helpers/assets';
+export type SeasonHistoryLabels = {
+    addSeason: string;
+    removeSeason: string;
+    seasonIdLabel: string;
+    seasonIdPlaceholder: string;
+    seasonIdInvalid: string;
+    untitledSeason: string;
+    linksHeading: string;
+    relationshipColumn: string;
+    entityIdColumn: string;
+    addLink: string;
+    removeLink: string;
+    noLinks: string;
+    assetsHeading: string;
+    attributesHeading: string;
+    attributeColumn: string;
+    valueColumn: string;
+    addAttribute: string;
+    removeAttribute: string;
+    noAttributes: string;
+    empty: string;
+    summary: string;
+};
+type SeasonHistorySectionProps = {
+    history: SeasonEntry[];
+    relationships: RelationshipDef[];
+    assetSlots: AssetSlot[];
+    attributeOptions: {
+        value: string;
+        label: string;
+    }[];
+    readOnly: boolean;
+    labels: SeasonHistoryLabels;
+    assetLabels: AssetLabels;
+    onUpload: (file: File, assetKey: string) => Promise<{
+        path: string;
+        url: string;
+    }>;
+    onError: (message: string) => void;
+    onChange: (history: SeasonEntry[]) => void;
+};
+/** Per-season squad, staff, assets and attributes. */
+declare const SeasonHistorySection: React.FC<SeasonHistorySectionProps>;
+export default SeasonHistorySection;

package/components/SportData/SelectionStrip.d.ts

@@ -0,0 +1,20 @@
+import { default as React } from 'react';
+type SelectionStripProps = {
+    selectedLabel: string;
+    createOverridesForLabel: string;
+    clientName: string;
+    clearLabel: string;
+    createLabel: string;
+    busy: boolean;
+    onClear: () => void;
+    onCreate: () => void;
+};
+/**
+ * Replaces the scope note while rows are selected.
+ *
+ * It takes the scope note's place rather than stacking below it because the two
+ * say different things about the same band of the screen, and the design treats
+ * them as one slot.
+ */
+declare const SelectionStrip: React.FC<SelectionStripProps>;
+export default SelectionStrip;

package/components/SportData/SocialsSection.d.ts

@@ -0,0 +1,17 @@
+import { default as React } from 'react';
+import { SocialSlot } from '../../helpers/socials';
+export type SocialsLabels = {
+    invalidUrl: string;
+    openLink: string;
+    summary: string;
+};
+type SocialsSectionProps = {
+    socials: Record<string, unknown>;
+    slots: SocialSlot[];
+    readOnly: boolean;
+    labels: SocialsLabels;
+    onChange: (key: string, value: string | null) => void;
+};
+/** Official channel URLs for an entity, one field per platform. */
+declare const SocialsSection: React.FC<SocialsSectionProps>;
+export default SocialsSection;