#![doc = include_str!("../README.md")]
#![forbid(unsafe_code)]
pub mod config;
pub mod contract;
pub mod runner;
use std::collections::BTreeSet;
use std::error::Error;
use std::fmt;
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum ControlKind {
Text,
Number,
Choice,
Toggle,
Color,
ReadOnly,
}
impl ControlKind {
#[must_use]
pub const fn label(self) -> &'static str {
match self {
Self::Text => "text",
Self::Number => "number",
Self::Choice => "choice",
Self::Toggle => "toggle",
Self::Color => "color",
Self::ReadOnly => "read only",
}
}
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct ArgType {
pub name: &'static str,
pub type_name: &'static str,
pub control: ControlKind,
pub default_value: &'static str,
pub description: &'static str,
pub options: &'static [&'static str],
}
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
pub enum StoryKind {
#[default]
Playground,
State,
Matrix,
Scene,
Documentation,
}
impl StoryKind {
#[must_use]
pub const fn label(self) -> &'static str {
match self {
Self::Playground => "playground",
Self::State => "state",
Self::Matrix => "matrix",
Self::Scene => "scene",
Self::Documentation => "documentation",
}
}
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct Story {
pub id: &'static str,
pub title: &'static str,
pub tier: &'static str,
pub kind: StoryKind,
pub description: &'static str,
pub source: &'static str,
pub args: &'static [ArgType],
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct Catalog {
name: &'static str,
stories: &'static [Story],
}
impl Catalog {
#[must_use]
pub const fn new(name: &'static str, stories: &'static [Story]) -> Self {
Self { name, stories }
}
#[must_use]
pub const fn name(self) -> &'static str {
self.name
}
#[must_use]
pub const fn stories(self) -> &'static [Story] {
self.stories
}
#[must_use]
pub const fn len(self) -> usize {
self.stories.len()
}
#[must_use]
pub const fn is_empty(self) -> bool {
self.stories.is_empty()
}
#[must_use]
pub fn story(self, id: &str) -> Option<&'static Story> {
self.stories.iter().find(|story| story.id == id)
}
pub fn validate(self) -> Result<(), CatalogError> {
validate(self.stories)
}
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct Viewport {
pub id: &'static str,
pub label: &'static str,
pub width: u16,
pub height: u16,
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct Surface {
pub id: &'static str,
pub label: &'static str,
pub value: &'static str,
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct Scene {
pub id: &'static str,
pub label: &'static str,
pub viewport: &'static str,
pub surface: &'static str,
}
pub const DEFAULT_VIEWPORTS: &[Viewport] = &[
Viewport {
id: "mobile393",
label: "Mobile 393",
width: 393,
height: 852,
},
Viewport {
id: "tablet768",
label: "Tablet 768",
width: 768,
height: 1024,
},
Viewport {
id: "desktop1280",
label: "Desktop 1280",
width: 1280,
height: 900,
},
];
pub const DEFAULT_SURFACES: &[Surface] = &[
Surface {
id: "canvas",
label: "Canvas",
value: "canvas",
},
Surface {
id: "inverse",
label: "Inverse",
value: "inverse",
},
Surface {
id: "grid",
label: "Grid",
value: "grid",
},
];
pub const DEFAULT_SCENES: &[Scene] = &[
Scene {
id: "mobile",
label: "Mobile",
viewport: "mobile393",
surface: "canvas",
},
Scene {
id: "desktop",
label: "Desktop",
viewport: "desktop1280",
surface: "canvas",
},
Scene {
id: "mobile-inverse",
label: "Mobile inverse",
viewport: "mobile393",
surface: "inverse",
},
Scene {
id: "desktop-grid",
label: "Desktop grid",
viewport: "desktop1280",
surface: "grid",
},
];
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum CatalogError {
DuplicateId(&'static str),
DuplicateArg {
story: &'static str,
arg: &'static str,
},
MissingId,
MissingTitle(&'static str),
MissingTier(&'static str),
MissingSource(&'static str),
ChoiceWithoutOptions {
story: &'static str,
arg: &'static str,
},
}
impl fmt::Display for CatalogError {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::DuplicateId(id) => write!(formatter, "duplicate story ID: {id}"),
Self::DuplicateArg { story, arg } => {
write!(formatter, "duplicate argument {arg} in story {story}")
}
Self::MissingId => formatter.write_str("story ID cannot be empty"),
Self::MissingTitle(id) => write!(formatter, "story {id} has no title"),
Self::MissingTier(id) => write!(formatter, "story {id} has no tier"),
Self::MissingSource(id) => write!(formatter, "story {id} has no source"),
Self::ChoiceWithoutOptions { story, arg } => {
write!(
formatter,
"choice argument {arg} in story {story} has no options"
)
}
}
}
}
impl Error for CatalogError {}
pub fn validate(stories: &[Story]) -> Result<(), CatalogError> {
let mut ids = BTreeSet::new();
for story in stories {
if story.id.trim().is_empty() {
return Err(CatalogError::MissingId);
}
if !ids.insert(story.id) {
return Err(CatalogError::DuplicateId(story.id));
}
if story.title.trim().is_empty() {
return Err(CatalogError::MissingTitle(story.id));
}
if story.tier.trim().is_empty() {
return Err(CatalogError::MissingTier(story.id));
}
if story.source.trim().is_empty() {
return Err(CatalogError::MissingSource(story.id));
}
let mut arg_names = BTreeSet::new();
for arg in story.args {
if !arg_names.insert(arg.name) {
return Err(CatalogError::DuplicateArg {
story: story.id,
arg: arg.name,
});
}
if arg.control == ControlKind::Choice && arg.options.is_empty() {
return Err(CatalogError::ChoiceWithoutOptions {
story: story.id,
arg: arg.name,
});
}
}
}
Ok(())
}
#[cfg(test)]
mod tests {
use super::{
ArgType, Catalog, CatalogError, ControlKind, DEFAULT_SCENES, DEFAULT_SURFACES,
DEFAULT_VIEWPORTS, Story, StoryKind, validate,
};
const LABEL: ArgType = ArgType {
name: "label",
type_name: "String",
control: ControlKind::Text,
default_value: "Enter briefing",
description: "Visible action copy.",
options: &[],
};
const STORIES: &[Story] = &[
Story {
id: "wordmark",
title: "Wordmark",
tier: "Atoms",
kind: StoryKind::State,
description: "Cold Front identity.",
source: "atoms.rs",
args: &[],
},
Story {
id: "action-link",
title: "Action link",
tier: "Atoms",
kind: StoryKind::Playground,
description: "Navigational action.",
source: "atoms.rs",
args: &[LABEL],
},
];
const DUPLICATE_ARGS: &[ArgType] = &[LABEL, LABEL];
#[test]
fn accepts_a_valid_catalog() {
assert_eq!(validate(STORIES), Ok(()));
}
#[test]
fn catalog_lookup_is_allocation_free() {
let catalog = Catalog::new("Cold Front", STORIES);
assert_eq!(catalog.name(), "Cold Front");
assert_eq!(catalog.len(), 2);
assert!(!catalog.is_empty());
assert_eq!(
catalog.story("action-link").map(|story| story.title),
Some("Action link")
);
assert!(catalog.story("unknown").is_none());
assert_eq!(catalog.validate(), Ok(()));
}
#[test]
fn defaults_reference_known_viewports_and_surfaces() {
for scene in DEFAULT_SCENES {
assert!(
DEFAULT_VIEWPORTS
.iter()
.any(|viewport| viewport.id == scene.viewport)
);
assert!(
DEFAULT_SURFACES
.iter()
.any(|surface| surface.id == scene.surface)
);
}
}
#[test]
fn rejects_duplicate_story_ids() {
let duplicate = [STORIES[0], STORIES[0]];
assert_eq!(
validate(&duplicate),
Err(CatalogError::DuplicateId("wordmark"))
);
}
#[test]
fn rejects_duplicate_arg_names() {
let stories = [Story {
id: "action-link",
title: "Action link",
tier: "Atoms",
kind: StoryKind::Playground,
description: "Navigational action.",
source: "atoms.rs",
args: DUPLICATE_ARGS,
}];
assert_eq!(
validate(&stories),
Err(CatalogError::DuplicateArg {
story: "action-link",
arg: "label",
})
);
}
}