SLGuiSkeleton.sleela
lib/gui/version-thual/SLGuiSkeleton.sleela · 221 line(s) · sleela
<< lib/gui/version-thual/SLGuiSkeleton.sleela
SLeeLa Standard Library Definition.
Definition: Defines SLGuiSkeleton — the SKELETON SCREEN / PLACEHOLDER
component: a subtle panel that fades IN to stand in for content that is
still loading, animates a gentle shimmer/pulse while it waits, and then
DISSOLVES to reveal the real content once loading completes. It is a pure
model + lifecycle state machine: idle -> loading(shimmer) -> revealing ->
revealed, driven by tick(elapsed). The initial appearance and the reveal
cross-fade are SLGuiTransitions; the shimmer is a looping 0..100..0 pulse.
SLeeLa owns the shape (how many placeholder lines/blocks) and the timing;
the host paints the grey blocks, the moving shimmer, and the reveal.
Family: gui. A loading placeholder; this model decides shimmer phase, panel
opacity, and when the real content is revealed. >>
#sleela 2.5
material;
class SLGuiSkeleton {
< ---- Descriptive metadata (version 1.11 nested-friendly accessors) ---- >
<< Eleven catalogued attributes with getter/setter pairs, so a GUI, loader,
or catalog can read and (where appropriate) override this record.
Values are faithful to the subject's real origin where publicly known. >>
String metaVersion = "1.0.0";
int metaId = 11398;
String metaAuthor = "Kiro Agent";
String metaDate = "2026-10-19";
String metaCopyright = "SLeeLa project";
String metaTrademark = "none";
String metaCorporation = "none";
< metaOrigin: National | <nation> | International | Galactic >
String metaOrigin = "International";
String metaBirthDate = "2026-10-19";
< metaScienceRating: maturity/robustness on a 1..10 scale >
int metaScienceRating = 9;
< metaNationalSchedule: a real, citable instrument or "none" >
String metaNationalSchedule = "none";
String getMetaVersion() { return metaVersion; }
void setMetaVersion(String v) { metaVersion = v; }
int getMetaId() { return metaId; }
void setMetaId(int v) { metaId = v; }
String getAuthor() { return metaAuthor; }
void setAuthor(String v) { metaAuthor = v; }
String getDate() { return metaDate; }
void setDate(String v) { metaDate = v; }
String getCopyright() { return metaCopyright; }
void setCopyright(String v) { metaCopyright = v; }
String getTrademark() { return metaTrademark; }
void setTrademark(String v) { metaTrademark = v; }
String getCorporation() { return metaCorporation; }
void setCorporation(String v) { metaCorporation = v; }
String getOrigin() { return metaOrigin; }
void setOrigin(String v) { metaOrigin = v; }
String getBirthDate() { return metaBirthDate; }
void setBirthDate(String v) { metaBirthDate = v; }
int getScienceRating() { return metaScienceRating; }
void setScienceRating(int v) { metaScienceRating = v; }
String getNationalSchedule() { return metaNationalSchedule; }
void setNationalSchedule(String v) { metaNationalSchedule = v; }
< Lifecycle states. >
< not shown >
static final int STATE_IDLE = 0;
< placeholder visible, shimmering >
static final int STATE_LOADING = 1;
< cross-fading placeholder -> content >
static final int STATE_REVEALING = 2;
< real content shown, placeholder gone >
static final int STATE_REVEALED = 3;
< Placeholder shape presets (host maps to a block layout). >
< stacked text lines >
static final int SHAPE_TEXT = 0;
< media block + text lines >
static final int SHAPE_CARD = 1;
< circle + two short lines >
static final int SHAPE_AVATAR = 2;
< repeated rows >
static final int SHAPE_LIST = 3;
< SHAPE_* >
int shape;
< number of placeholder blocks/rows, 1..32 >
int lines;
< STATE_* >
int state;
< one full shimmer sweep, 200..10000 ms >
int shimmerPeriodMs;
< position within the current sweep >
int shimmerElapsed;
< the placeholder's initial fade-in >
SLGuiTransition appearFx;
< the placeholder -> content dissolve (cross-fade) >
SLGuiTransition revealFx;
int clamp(int v, int lo, int hi) {
if (v < lo) { return lo; }
if (v > hi) { return hi; }
return v;
}
< Safe defaults: a 3-line text skeleton, 180ms fade-in, a 1.2s shimmer sweep, >
< a 260ms dissolve reveal. >
void configure(int shapeVal, int lineCount) {
shape = (shapeVal >= SHAPE_TEXT && shapeVal <= SHAPE_LIST) ? shapeVal : SHAPE_TEXT;
lines = clamp(lineCount, 1, 32);
state = STATE_IDLE;
shimmerPeriodMs = 1200; shimmerElapsed = 0;
appearFx = new SLGuiTransition(); appearFx.configure();
< 2 = SLGuiTransition.EASE_OUT >
appearFx.fadeIn(180, 2);
revealFx = new SLGuiTransition(); revealFx.configure();
< 4 = SLGuiTransition.EASE_DISSOLVE >
revealFx.fadeIn(260, 4);
}
void setShape(int shapeVal) { if (shapeVal >= SHAPE_TEXT && shapeVal <= SHAPE_LIST) { shape = shapeVal; } }
void setLines(int n) { lines = clamp(n, 1, 32); }
void setShimmerPeriod(int ms) { shimmerPeriodMs = clamp(ms, 200, 10000); }
void setAppearMillis(int ms) { appearFx.setDuration(ms); }
void setRevealMillis(int ms) { revealFx.setDuration(ms); }
< ---- lifecycle ---------------------------------------------------------- >
< Begin loading: fade the placeholder in and start shimmering. >
void beginLoading() {
state = STATE_LOADING;
appearFx.reset();
shimmerElapsed = 0;
}
< Content is ready: start the dissolve reveal. >
void complete() {
if (state == STATE_IDLE || state == STATE_REVEALED) { return; }
state = STATE_REVEALING;
revealFx.reset();
}
void reset() { state = STATE_IDLE; shimmerElapsed = 0; }
< Advance by `deltaMs`. Returns true while the placeholder is still visible >
< (loading or revealing), false once the real content is fully revealed/idle. >
boolean tick(int deltaMs) {
if (deltaMs < 0) { deltaMs = 0; }
if (state == STATE_LOADING) {
if (!appearFx.done()) { appearFx.advance(deltaMs); }
shimmerElapsed = shimmerElapsed + deltaMs;
while (shimmerElapsed >= shimmerPeriodMs) { shimmerElapsed = shimmerElapsed - shimmerPeriodMs; }
return true;
}
if (state == STATE_REVEALING) {
revealFx.advance(deltaMs);
if (revealFx.done()) { state = STATE_REVEALED; return false; }
return true;
}
< STATE_IDLE / STATE_REVEALED >
return false;
}
< ---- presentation ------------------------------------------------------- >
< Opacity (0..100 %) to paint the PLACEHOLDER panel at. During the reveal the >
< placeholder fades OUT as the content fades in (1 - reveal progress). >
int placeholderOpacityPct() {
if (state == STATE_LOADING) { return appearFx.opacityPct(); }
if (state == STATE_REVEALING) { return 100 - revealFx.opacityPct(); }
return 0;
}
< Opacity (0..100 %) to paint the real CONTENT at. Rises during the reveal. >
int contentOpacityPct() {
if (state == STATE_REVEALING) { return revealFx.opacityPct(); }
if (state == STATE_REVEALED) { return 100; }
return 0;
}
< Shimmer phase as a 0..100 % sweep position (host sweeps a highlight band). >
int shimmerPhasePct() {
if (shimmerPeriodMs <= 0) { return 0; }
return clamp((shimmerElapsed * 100) / shimmerPeriodMs, 0, 100);
}
boolean onScreen() { return state == STATE_LOADING || state == STATE_REVEALING; }
boolean revealed() { return state == STATE_REVEALED; }
< ---- readers ------------------------------------------------------------ >
int getShape() { return shape; }
int getLines() { return lines; }
int getState() { return state; }
int getShimmerPeriod() { return shimmerPeriodMs; }
SLGuiTransition appearTransition() { return appearFx; }
SLGuiTransition revealTransition() { return revealFx; }
String shapeName() {
if (shape == SHAPE_CARD) { return "card"; }
if (shape == SHAPE_AVATAR) { return "avatar"; }
if (shape == SHAPE_LIST) { return "list"; }
return "text";
}
String stateName() {
if (state == STATE_LOADING) { return "loading"; }
if (state == STATE_REVEALING) { return "revealing"; }
if (state == STATE_REVEALED) { return "revealed"; }
return "idle";
}
boolean honored() {
if (lines < 1 || lines > 32) { return false; }
if (shimmerPeriodMs < 200 || shimmerPeriodMs > 10000) { return false; }
int p = placeholderOpacityPct(); int c = contentOpacityPct();
return p >= 0 && p <= 100 && c >= 0 && c <= 100
&& appearFx.honored() && revealFx.honored();
}
< Flatten into the reconciler's style descriptor. Shape: >
< "skeleton:<shape>x<lines>;shimmer:<ms>;<appear>;reveal-<dissolve>" >
String toStyle() {
return "skeleton:" + shapeName() + "x" + lines + ";"
+ "shimmer:" + shimmerPeriodMs + ";" + appearFx.toStyle()
+ ";reveal-" + revealFx.toStyle();
}
String report() {
return "skeleton [" + shapeName() + " x" + lines + "]: " + stateName()
+ " placeholder=" + placeholderOpacityPct() + "% content=" + contentOpacityPct()
+ "% shimmer=" + shimmerPhasePct() + "%";
}
}